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Preface 

The first section of this book, How to Use This Book defines the audience for 
which this programmer's guide is intended, explains how the book is organized, 
and suggests how the reader might best famiUarize himself with its contents. The 
chart below hsts alphabetically the key words that are used throughout the book 
to refer to other publications; accompanying the key words are the corresponding 
title and order number to which the key words refer. 
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Order No. 


Assembler 
Language 


IBM System/360 Operating System 
Assembler Language 


GC28-6514 
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Planning Guide 


IBM System/360 Operating System 
Advanced Checkpoint/Restart 
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Data Management 
Services 


IBM System/360 Operating System 
Data Management Services 
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Job Control 
Language 


•IBM System/360 Operating System 
JCL User's Reference 


GC28-6704 


Messages and Codes 


IBM System/360 Operating System 
Messages and Codes 
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Operator's Guide 


IBM System/360 Operating System 
Operator's Reference Manual 


GC28-6691 


TCAM User's 
Guide 


OS TCAM User's Guide 


GC30-2025 


Principles of 
Operation 


IBM System/360 Operating System 
Principles of Operation 


GA22-6821 


Programmer's Guide 
to Debugging 


IBM System/360 Operating System 
Programmer's Guide to Debugging 


GC28-6670 
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Supervisor and Data 
Management Macro 
Instructions 



IBM System/360 Operating System 
Data Management Macro Instructions 



GC26-3794 



Supervisor Services 


IBM System/360 Operating System 
Supervisor Services and Macros 


GC28-6646 


System Generation 


IBM System/360 Operating System 
System Generation 


GC28-6554 


TCAM Concepts and 
Facilities 


OS TCAM Concepts and Facilities 


GC30-2022 



TCAM Level 4 
Component Release 
Guide 



TCAM Level 4 Component Release 
Guide 



GC30-1007 



TCAM PLM 


OS/MFT and OS/MVT TCAM Logic 


GY30-2029 


TSO Command 
Language 


IBM System/360 Operating System 
TSO Command Language Reference 


GC28-6732 


TSO Guide 


IBM System/360 Operating System 
TSO Guide 


GC28-6698 


Utilities 


IBM System/360 Operating System 
Utilities 


GC28-6586 



Summary of Amendments 



This revised edition incorporates the following programming information that 
applies to OS Release 21.0 (Component Release 4 of OS/MFT and OS/MVT 
TCAM): 

2790 Data Communications System support. 

3270 Information Display System support. 

3670 Brokerage Terminal support. 

7770 enhancements. 

BSCl, BSC2, BSC3 device types. 

Disk error handling. 

General Poll for 2260 and 3270. 

Reverse Interrupt (RVI) support. 

TOTE II On-Line Test facility (OLT). 

TSO/TCAM Mixed Environment and 3270 support. 

Macros changed: 



DATETIME 
ERRORMSG 
FORWARD 
GET 
INTRO 
INVLIST 
LOCK 
LOCOPT 
New macros: 
COMMBUF 



MSGFORM 

MSGTYPE 

ORIGIN 

POINT 

PUT 

QACYION 

QCOPY 

SCREEN 

QRESET 



SETEOM 

TERMINAL 

TPROCESS 

TTABLE 

UNLOCK 

WRITE 



MHGET SLOWPOLL 

MHPUT TYPETABL 

• New operator commands: 

GENPOLOFF GENPOLON 

Also included are minor corrections and format changes throughout the pubUca- 
tion that apply to maintenance support of OS/MFT and OS/MVT TCAM in OS 
Release 21.0. The previous edition of this manual, GC30-2024-2, incorporated 
the following information that applies to OS Release 20.7 (Component Release 2 
of OS/MFT and OS/MVT TCAM): 

• Defining logical messages (see Handling Logical Messages) . 

• Concen^trating and deconcentrating messages (see Appendix J ). 

• Recovering from text errors in multiblock messages (see Mid-Batch Recovery ). 

• Editing data across buffer boundaries (see the MSGEDIT functional MH 
macro). 

• Removing line-control characters on a count basis from incoming messages and 
permitting variable-length reblocking of records for outgoing messages (see the 
MSGFORM functional MH macro). 

• Retrying to dial a switched station (see the RETRY functional MH macro). 

• Determining how many complete messages are queued for the apphcation 
program (see the MCOUNT application program macro). 

• Recording date and time that messages are received at the apphcation program 
(see the TPDATE application program macro). 

• Including the IBM 3735 Programmable Buffered Terminal in a TCAM net- 
work. 

• Including the Attention Interrupt feature for the IBM 1050 and 2741 terminals. 
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How To Use This Book 



This book is a reference manual and coding guide for the system programmer who 
must construct or modify a TCAM Message Control Program, or an appUcation 
programmer who must write a TCAM-compatible appUcation program. Familiari- 
ty with the overall concepts and structure of TCAM is assumed; a good way to 
achieve this familiarity is to read the TCAM Concepts and Facilities publication. 

The first seven chapters of the book are concerned with tasks you will encounter 
in constructing a TCAM Message Control Program (MCP), such as defining 
buffers, defining data sets, activating and deactivating an MCP, and actually 
putting an MCP together. The eighth chapter tells how to make your application 
programs compatible with a TCAM MCP. Following this is a chapter telling how 
to use auxiUary services provided by TCAM, such as the checkpoint/restart 
facility, the operator control capability, and the on-line test function. The final 
chapter contains information that might be useful in planning and setting up an 
actual teleprocessing system incorporating TCAM — including TCAM's machine 
and device requirements, a list of stations supported by TCAM, system-generation 
considerations specific to TCAM, and directions for Preformatting TCAM data 
sets residing on disk. 

Several appendixes containing special, helpful information for the system program- 
mer are located in the back of this publication. They include macro instruction 
formats, transmission-code charts, and aids for conversion from QTAM to 
TCAM. Of particular interest to the system programmer is the appendix on 
device-dependent considerations, which should be read before an MCP is coded. 
Throughout this publication, wherever a particular device dependency would 
appear, a reference is made to this appendix instead of Hsting the individual 
consideration. Appendix I contains macro descriptions and coding considerations 
for the system programmer who incorporates the Time Sharing Option (TSO) in 
his system; it is intended primarily for the programmer who designs his own TSO 
message-handling facilities rather than use an IBM-supplied message-handling 
routine for TSO applications. Appendix J contains macro descriptions and coding 
considerations for the system programmer who incorporates a message concen- 
trating device in his teleprocessing network. 

As a first step in famiharizing yourself with this book, look over the table of 
contents. This book is organized around user tasks, rather than around macros. In 
defining buffers or terminal- and line-control areas, you must code operands of 
several macros. If the book were organized around the macros, you would have to 
look at each operand of each macro to determine which operands pertained to 
buffer definition, which to terminal- and line-control-area definition, which to 
incorporating a checkpoint facility, etc. Because the book is organized around 
tasks, rather than macros, you are saved much of this work. For example, the 
chapter Defining Buffers contains a checklist of those TCAM macro operands 
having to do with buffer definition. One of the macros mentioned in this checklist 
happens to be located in the chapter Activating and Deactivating the Message 
Control Program , another is in the chapter Defining the MCP Data Sets , a 
third in the chapter Defining Terminal and Line Control Areas . By discussing 
together those operands having to do with buffers in a section titled Defining 
Buffers , the book saves you the trouble of haying to locate these operands your- 
self when you design and specify your buffers. 
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In addition, the task-oriented organization facilitates retrieval of information: to 
locate information on TCAM's reusable disk queuing scheme you need only relate 
reusable disk queuing to the task of defining the MCP data sets and look in the 
table of contents under the chapter-heading Defining the MCP Data Sets . 
Similarly, to locate information on TCAM's checkpoint facility, you need only 
remember that this is a service facility and look under the chapter-heading Using 
TCAM Service Facilities . Of course, this method of retrieving information by 
relating it to tasks will work only if you are aware of the tasks we discuss. Each 
chapter heading shown in the table of contents is the name of one such task. 

References to other books appear in this publication in a shortened form; their 
complete titles and order numbers appear in a table in the Preface . 
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What the Message Control Program Is 

The Message Control Program (MCP) is a set of routines that identify the telepro- 
cessing network to the IBM System/ 3 60 operating system, estabUsh line control 
required for the various kinds of stations and modes of connection, and control 
the handling and routing of messages in accordance with the user's requirements. 
Every teleprocessing system operated under TCAM requires one MCP. 

The MCP serves as an intermediary between the remote stations, and between a 
remote station and an appUcation program. Device-dependent input/output 
operations are performed by TCAM routines in the MCP, based on station and 
Une configurations of the system as specified in the operands of TCAM macro 
instructions in the MCP. 

An MCP is coded using a group of TCAM macro instructions. Coding require- 
ments and restrictions for a TCAM macro are identical to those for any other 
assembler language macro instruction. Assembler language conventions for 
coding continuations, comments, symbols, and the length, number, and format of 
operands apply to all TCAM macros. 



Functions of the MCP 



Depending on the requirements of the user, the TCAM MCP might perform any 
of the following specific functions: 

• Enable and disable communication lines. 

• Invite terminals to transmit messages. 

• Receive messages from terminals. 

• Dynamically assign buffers to incoming messages. 

• Handle messages on the basis of user-specified priorities. 

• Perform message-editing functions for incoming messages. Among such 
functions are the following: translating from the transmission-code to 
EBCDIC code; deleting line-control characters; inserting time-received and 
date-received information in the message header; recording the message on a 
secondary storage medium (logging); inserting or removing user-specified data 
in the header; maintaining a count of the number of messages received from 
each station. 

• Determine the appropriate destination queue for a message and route the 
message to that queue. 

• Queue the message on the appropriate destination queue. 

• Place response messages generated by application programs on queues for 
subsequent transmission. 

• Retrieve messages from destination queues and prepare them for transmission 
to stations. 

• Perform message-editing functions for outgoing messages. Among such 
functions are the following: placing time-sent and date-sent information in the 
message header; placing an output sequence number in the header; inserting or 
removing user-specified data in the header; logging the outgoing message on a 
secondary storage device; maintaining a count of the number of messages sent 
to each terminal; inserting line-control characters; translating the message from 
EBCDIC code to the appropriate transmission code. 
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• Take periodic checkpoints of the system. 

• Provide operator-to-system communications through system control terminals. 

• Initiate corrective action when an error or unusual condition is detected. 

• Cancel incoming messages containing errors. 

• Reroute messages with erroneous header information to a special queue. 

• Transmit error messages. 

User Tasks in Writing the MCP 

As a system programmer concerned with writing a Message Control Program, you 
will be confronted with five basic tasks: 

1. Defining the various terminal and line control areas used by the MCP; 

2. Defining the buffers used by the MCP for handling, queuing, and transferring 
message segments; 

3. Defining the data sets referred to by the MCP; 

4. Activating and deactivating the MCP data sets; 

5. Defining the Message Handlers, the sets of routines that examine and process 
control information in message headers, prepare message segments for forward- 
ing to their destination, and route messages to their proper destinations. 

In the next five chapters, we shall consider each of these tasks in detail. 
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Defining Terminal and Line Control Areas 



In constructing the Message Control Program, the user must provide control 
information that identifies the remote stations, specifies their characteristics to the 
system, and tells how they are to be handled by TCAM. This chapter describes 
how this information is specified. 



Terminology 



In the following discussion, the word computer refers to the central computer in 
the TCAM system; this is the computer that contains the Message Control 
Program. Remote terminals, as well as remote computers, are referred to as 
stations . 



Line Control 



A nonswitched line (also known as a leased or dedicated line) is one over which 
connections between the computer and remote stations are continuously estab- 
lished. A switched line (also known as a dial line) is one over which a direct 
physical connection between the computer and a remote station must be estab- 
lished by dialing for data transmission to occur. 

A point-to-point line connects a single remote station to the computer. Switched 
lines are considered to be point-to-point. A multipoint line connects two or more 
stations to the computer. For lines to Binary Synchronous Communications 
(BSC) stations, a Hne to one station is considered to be multipoint if multipoint 
ESC data-Hnk control is used on the line. 

A contention line is one over which the computer and a station may vie for use of 
the Une. Either the computer or a station may "seize" the line, thereby preventing 
its use by another device on the Une until after the device that gained control of 
the line has transmitted its messages and relinquished control. All TCAM- 
supported stations not assigned poUing or addressing characters, except BSC dial 
lines, are considered to be contention stations. A non-contention line is one for 
which the computer, using certain user-specified information, determines which 
station is permitted to enter or accept messages at any particular time. 

The computer sends a message to a station and receives a message from a station; 
sending and receiving are functions of the computer. 

A station enters a message to be transmitted to the computer and accepts a 
message transmitted to it from the computer; entering and accepting are functions 
of a station. 



Just as a computing system, with its variety of peripheral input/output equipment, 
requires some means to coordinate the functioning of the various parts, the variety 
of I/O equipment comprising a teleprocessing system requires a discipline to 
effectively manage the flow of message traffic. A significant difference should be 
noted, however. In a conventional computing system, the various I/O devices are 
at the service of the programmer; the requirements of his program and the charac- 
teristics of the data to be processed largely determine which input and output 
devices are to be activated and when. Moreover, the I/O devices are within reach 
of the computer operator; he can intervene when a device malfunctions to correct 
the condition or to assign a different device. In a teleprocessing system, on the 
other hand, the central computer receives data at random from remote stations, 
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and the operator at the central computer cannot exercise any direct control over 
remote stations. He cannot, for example, correct a malfunctioning device at a 
remote station. 

A further distinction between a computing system and a teleprocessing system lies 
in the handling of errors in data. With current techniques for transmitting data 
over long distances, errors can be introduced into message data by unavoidable 
transient Une conditions, such as crosstalk and Ughtning strikes. Transmission 
errors occur much less often in a computing system. A discipline for a telepro- 
cessing system must detect transmission errors and, when possible, correct them 
(as by retransmitting the message containing the errors). If the error cannot be 
recovered from, its occurrence must be indicated to the user program so that 
appropriate action can be taken. 

The scheme of operating procedures and signals by which a teleprocessing system 
is managed is called line control (for binary synchronous communications, the 
term data-link control is often used). A line control scheme must consider the 
functional characteristics and capabilities of the equipment and communication 
lines comprising the system, as well as the operational requirements of the system. 
Some specific factors that line control must consider are: How is contact to be 
estabhshed between a sending and a receiving station? How is a message to be 
directed to a specific station on a multistation line? What if two stations try to 
send at the same time? What should be done if a station fails to respond to a 
message? 

Line control can be classified in two ways. The first way is by the transmission 
technique (start-stop or BSC) used for the Une under consideration. A set of 
control characters and rules for their use is associated with each of these tech- 
niques to effect the needed functions. Some of the control characters are used for ' 
both start-stop and BSC transmission, while others are pecuHar to one or the other 
of the transmission techniques. For a discussion of these transmission techniques, 
see the TCAM Concepts and Facilities publication. 

The second way in which Une control can be classified is by the communication 
line configuration with which it is used. For example, line control for a switched 
Une differs from that for a nonswitched line in the way in which initial contact is 
made. 

While a given line-control scheme is identified in terms of transmission technique 
and line configuration, differences may arise in the stations to be controlled and 
by the presence or absence of certain features in the stations. For example, a 
given Une-control scheme may include the control characters needed to indicate a 
transmission error and to request automatic retransmission, but some station 
equipment using that line-control scheme may not be capable of error checking or 
automatic retransmission. Generally speaking, aU stations connected to a given 
Une must be designed to use the same Une-control scheme, and where a certain 
capability is provided by some stations but not by others, the capabiUty cannot be 
used. 

It is not necessary for the TCAM programmer to specify the Une-control scheme 

to be used for a given line; this information is provided impUcitly at system 

generation time, at assembly time in the DCB macro instruction for the line group 

of which the given Une is a member, and in the TERMINAL macro instructions 

for the stations on the line. The programmer must, however, have a general I 

understanding of Une-control concepts to correctly structure that portion of his 
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program involved in message transmission, and to decide intelligently how to deal 
with line-control characters in his message. 

For start-stop stations, the line-control characters recognized by TCAM are EOA 
and BOB. For BSC stations, the line-control characters recognized by TCAM are 
STX, ETB, and ETX. TCAM removes all of these line-control characters except 
the EOT from incoming messages if the LC= operand of the STARTMH macro is 
coded LC=OUT, and leaves them in incoming messages if the LC= operand is 
coded LC=IN (except that line-control characters are always removed from 
incoming messages in transparent mode). TCAM inserts line-control characters 
into outgoing messages if the MSGFORM macro is coded in the outheader 
subgroup of the Message Handler (MH) handling the outgoing message. 

If the station that enters the message and the stations that are to accept it are 
either all similar start-stop or all BSC, and if the user does not wish to change the 
size of physical blocks of data in the message (if the message is divided into such 
blocks by EOB or ETB line-control characters), then line-control characters may 
be left in the message. If the originating and destination stations use different line 
codes, then the CODE macro must be issued at appropriate places in the MH so 
that TCAM can translate the message from the Une code for the originating 
station to EBCDIC, then to the line code for the destination station. TCAM's 
translation tables are set up so that Une-control characters for an originating 
station using one Une code are translated into satisfactory characters in the line 
code for the destination station, provided that both the originating and the desti- 
nation stations are either similar start-stop or BSC devices. 

If incoming data is being blocked to form logical messages, the LC=OUT operand 
of STARTMH should be specified to remove line-control characters, and the 
MSGEDIT functional MH macro should be used to remove EOT characters 
included in the message. 

Line control may be left in a message that is processed by a TCAM appUcation 
program; of course, the user code in the application program will have to take 
account of line-control characters if they are left in the message. 

For a message sent between a start-stop and a BSC station, whether directly or 
through an appUcation program, the conversion of Une-control characters by 
TCAM's translation tables is less likely to be satisfactory. Figure 40 in Appendix 
D is a chart showing the line-code equivalents of EBCDIC graphic and control 
characters for each station supported by TCAM. This chart may be used to 
determine the character to which TCAM's translation tables wiU translate an 
incoming character. For example, an incoming ETB character from a BSC station 
using EBCDIC line code, if left in the message, will be translated to an EOB 
character if TCAM's 1050 translation table is used to translate the message from 
EBCDIC to 1050 line code. (The translation table to be used by TCAM is 
specified by means of the TRANS= operand of the line group DCB macro, while 
the CODE macro causes translation to be performed and may be used to override 
the translation table specified in the DCB.) 

If the user switching messages between stations having different Une codes is 
satisfied with the equivalent characters provided by TCAM's translation tables, 
and if he is satisfied with the size of the physical blocks (if any) in his message, he 
may leave line-control characters in his message; otherwise, he should remove 
line-control characters from the incoming message by specifying LC=OUT in his 
STARTMH macro, and insert appropriate Une-control characters in his outgoing 
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message by coding a MSGFORM macro in the outgoing group of the Message 
Handler handhng the message. 

Operands of MSGFORM permit the user to specify fixed outgoing blocking 
factors, some of which may be overridden on a terminal-by-terminal basis. They 
also permit him to specify variable-length blocking for outgoing messages. The 
user specifies the number of subblocks for each block and the character that 
delimits each subblock. The user who wishes to specify physical blocks of data 
that differ in length within the same message may do so by inserting the appropri- 
ate line-control characters in his outgoing message by coding the MSGEDIT 
macro. 

TCAM does not consider the ITB control character in BSC to be a line-control 
character and does not remove it from incoming messages when LC=OUT is 
coded in the STARTMH macro. The user may delete ITB characters by coding 
the MSGFORM macro in the inblock subgroup. The MSGEDIT macro may be 
used to remove and insert ITB characters, and the BLOCK= operand of the 
MSGFORM macro may be used to specify a fixed interval at which ITB charac- 
ters are to be inserted by TCAM into outgoing messages. 

For BSC stations, another transmission variable involves the treatment of hne- 
control characters in a message. BSC messages may be transmitted in transparent 
mode or in nontransparent mode. 

The transparent mode is a type of BSC transmission in which message segments 
may include certain normally restricted data-Unk control characters, which are 
transmitted as ordinary data and not as functional control characters; the only 
functional data-Unk control characters transmitted when a message is in transpar- 
ent mode are those preceded by a DLE data-link character. Transparent mode is 
useful in transmitting messages containing binary data, fixed- and floating-point 
data, packed decimal digits, source programs, and object programs, because with 
such messages the binary structure of a character may be the same as that for a 
data-link control character. 

When a message in transparent mode arrives at the computer, TCAM automatical- 
ly removes the two initial line-control characters and all functional ETB and ETX 
control characters. All DLE STX sequences are also removed, except those 
immediately following an ITB. These characters are removed whether or not 
LC=OUT is coded in the STARTMH macro. If the user wishes to remove the 
ITB, DLE, STX sequence, he may specify a MSGFORM macro in the inblock 
subgroup of his Message Handler. If the user wishes to place a message in trans- 
parent mode before sending it to a BSC station, he issues a MSGFORM macro 
specifying SENDTRP= YES in the outheader subgroup handUng messages for that 
station. 

In nontransparent mode , all line-control characters are treated as such, and line 
control is handled as it is for start-stop stations. 

In deciding whether to remove and insert line-control characters, and whether 
messages to BSC stations are to be in transparent mode, the TCAM programmer 
is concerned with Une control at the character level. On a more general basis, he 
must make decisions regarding those line-control functions used by TCAM to 
establish contact between the computer and remote stations, and those functions 
used to maintain an orderly flow of message traffic. The rest of this chapter 
contains information to help him make and implement these decisions. 
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Establishing Contact 



With TCAM, contact for the purpose of message transmission may be estabUshed 
in several ways, depending upon the line configuration and the stations involved. 
Contact is always established under the control of the central computer, which 
performs (in the channel) a number of ''set-up" or preparatory operations, which 
are followed by either a Read or a Write operation on the line (except when the 
set-up operations determine that the remote station is not free to enter or accept 
data, in which case no message transmission occurs). 

In this pubUcation, when contact is established for the purpose of receiving data 
from a station, the process is called invitation ; when contact precedes the sending 
of data to a station, the process of establishing contact is called selection . Selec- 
tion is performed when the central computer has a message to send to a station; 
invitation is performed to give a station the opportunity to enter a message if it 
has one ready (in some cases of invitation, the station initiates contact with the 
computer to enter a message and the computer completes the invitation process). 



Invitation 



There are two forms of invitation: contention (with or without identification 
sequence exchange) and polling . 

In a TCAM system either the computer or a station on a point-to-point conten- 
tion line can *'bid" for use of the line so that it can send a message to another 
device. In some configurations, it is possible for both the computer and the 
station to simultaneously bid for the line; when this happens, the computer and 
the station are said to contend with each other (hence the name contention line ). 

For contention stations, invitation by TCAM means that TCAM gives the station 
an opportunity to enter data, that is, TCAM ''Ustens" on the line for a signal from 
the station indicating that the station wishes to enter a message. 

The alternative to contention involves having the central computer periodically 
examine each active entry in an invitation Ust (discussed below) of remote stations 
and invite each station to enter any input messages it has ready. Each station in 
the list has a unique identifier, usually consisting of one or two characters that 
cause that station, and no other, to respond. The process of contacting each 
remote station in this manner is called polling , and the station identifiers are 
called polling characters . Often, the first polUng character identifies the station 
and the second identifies a particular component of the station. 

For polled nonswitched lines, TCAM commences invitation by polling the first 
station Usted in the invitation list for the line. (If the line is point-to-point, the 
first will be the only station on it, and the invitation Ust for the Une need contain 
only one entry.) TCAM uses polling characters unique to each station to deter- 
mine, station by station, whether there is a message to send. If a response is 
negative, or if there is no response (that is, if the station is down), the polling 
characters for the next station Usted are sent; this process is repeated until a 
station responds positively by entering a message. When there is no response, a 
timeout wiU occur on the read response to polling. TCAM error recovery (ERP) 
modules wiU gain control to retry the polling operation. This time-out is consid- 
ered a temporary error, and TCAM will retry until either a response is received or 
a STOPLINE is performed. To prevent system degradation due to high ERP 
activity TCAM should not be started on a Une for which a terminal wiU f aU to 
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respond. Such a station is permitted to enter any messages it may have ready for 
the computer and may be sent any messages that are queued for it (see 
Transmission Priority in this chapter for a discussion of when sending to a station 
may occur relative to receiving). After all messages are entered, the computer 
interrogates the next station in the invitation list. After all the active stations in 
an invitation list for a given polled line have been invited to enter a message, a 
delay (equal to the number of seconds specified in the INTVL= operand of the 
DCB macro for the line group) may be observed to allow for sending before 
polling is restarted at the beginning of the list; if this operand is omitted, no delay 
occurs. The polling interval reduces unproductive polling on lines that are not used 
continually. 

For nonswitched polled lines, the computer initiates contact with the stations. 
However, for switched lines the station may initiate the contact by successfully 
dialing the computer. The polling function in this case consists only of sending the 
polling characters to the station that initiates the contact. The station responds by 
entering one or more messages. The computer sends the polling characters after 
each message is received. 

It is possible for the computer to dial some types of polled stations on switched 
lines. The user may specify computer-initiated contact by coding certain operands 
of the TERMINAL macro, discussed below. In this case, the polling characters 
for the station are sent once contact has been established and all messages queued 
for the station have been transmitted. 

Constructing the Invitation List 

A TCAM system maintains control of invitation by having an invitation hst, 

created by an INVLIST macro instruction, for each line. (. 
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symbol 



INVLIST 



The INVLIST macro 

• generates the invitation list for a line; 

• specifies active and inactive invitation list entries; 

• is required for each line in the system (though the same INVLIST macro may 
be sufficient for more than one output-only line); 

• is specified following the macros defining the terminal table. 

• indicates whether TCAM is the master or slave in a contention situation on a 
BSC device. 

One INVLIST macro must be issued for each line in the system, with the excep- 
tion of output-only lines to stations that do not use invitation sequences; a single 
INVLIST macro is sufficient for all such output-only Unes. The names of all 
INVLIST macros for the lines in a line group must be specified, by ascending 
relative line number, in the INVLIST = operand of the DCB macro for the line 
group. 

For each station on a line, the INVLIST macro creates an invitation list entry that 
contains the invitation characters for the station (the polling characters for polled 
stations, or the identification sequence assigned to TWX and switched BSC 
stations using such a sequence). See Appendix G. Device-Dependent 
Considerations , for particular invitation list specifications for the: 

• 2260 Display Stations, both local and remote; 

• 2740 Communications Terminal with the Station Control or Station Control 
and Checking feature; 

• BSC terminals; 

• 2740 Communications Terminal with the Transmit Control or Transmit Con- 
trol and Checking feature; 

• TWX terminals; 

• 7770 Audio Response Unit, Model 3. 

No invitation characters are present in entries for contention terminals not 
assigned identification sequences. 

INVLIST has the following format: 



Name 


Operation 


Operands 


symbol 


INVLIST 


ORDER=(entry,...)[,EOT=hexchars] 
[,CPUID=addr] l,MASTER= YES] 

NO 



Function: Specifies the name of the macro and of the invitation list for the line. 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Notes: This name must be the same as the name specified by the INVLIST= 

operand of the DCB macro for the line group containing this line. 
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ORDER= (entry,...) 



EOT=hex chars 



CPUID=addr 



Function: Specifies the invitation list entries for the Hne. 

Default: None. For all output-only lines to stations having no ID sequence 

assigned to them, specification optional. For all other cases, this operand must be 

specified. 

Format: The exact manner in which each entry is coded is described below. A 

maximum of 200 entries may be coded. 

Notes: For polled lines, there must be at least one entry for each station that can 

enter messages on the line. Entries are specified in the order in which the stations 

are to be invited to send messages. 



Function: Specifies the EOT line-control character for the stations on this line. 

Default: None. For Hnes to multipoint BSC stations, this operand must be 

specified. For all other cases, this operand must not be specified. 

Format: A single hexadecimal character, unframed, in the transmission-code 

representation. 

Notes: Appropriate EOT characters are as follows: 

. for EBCDIC: 37 

. for ASCII: 04 

• for 6-bit Transcode: IE 

Example: 

For a hne to multipoint BSC stations using ASCII as their transmission-code, this 
operand would be coded as follows: 

EOT=04 

where 04 is the ASCII transmission-code representation of the EOT control 
character, in hexadecimal notation. 



Function: Specifies the name of a field containing the ID sequence assigned to the 

computer. 

Default: None. For switched lines to stations using ID sequences, when the 

computer is expected to exchange ID sequences with stations on the line when 

calls are made, this operand must be specified. For all other cases, specification 

optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The field named by addr should consist of a length byte, specifying in 

binary form the number of characters in the computer ID sequence, followed by 

the ID sequence itself in line code. For more information on ID sequences, see 

Switched Line to Stations Using ID Sequences below. This operand also 

specifies the invitation message for audio terminals. 

Example: 

For a switched line to stations using ID sequences and EBCDIC line code, this 
operand might be coded as follows: 

CPUID=CPUNAME 



Somewhere within the same area of addressabihty in the MCP the following field 
might be defined: 



CPUNAME 



DC X'04' 

DC X'D5D6D3C1 ' 
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MASTER^ \ YES 
NO 



Here, X'04' is the hexadecimal number of bytes in the rest of the field, while 
X'D5D6D3Cr is the EBCDIC character sequence NOLA in hexadecimal nota- 
tion. 



Function: Specifies whether TCAM assumes the role of master or slave in point- 
to-point, nonswitched contention situations. See Appendix G. Device-Dependent 
Considerations for Binary Synchronous Communication (BSC) Terminals. 
Default: NO 

Format: MASTER=YES or MASTER=NO 

Notes: MASTER=YES indicates that TCAM will continue to bid for the line in a 
contention situation until the contention is resolved. MASTER=NO indicates 
that TCAM will discontinue bidding for the line in a contention situation. This is 
normal operation for point-to-point, nonswitched, contention stations as de- 
scribed in TCAM Send and Receive Operations on a BSC Line in Appendix 
G. 

Each entry specified as a suboperand of the ORDER= operand consists of a 
station or line name, an indicator that determines whether the station represented 
by the entry is initially capable of entering messages, and a sequence of invitation 
characters. This sequence of invitation characters is limited to 46 alphameric 
symbols (23 hexadecimal bytes). 

The station name must be the name of the TERMINAL macro for the station 
being entered in the list. 

The indicators to distinquish active from inactive entries are as follows: 

+ indicates that the station represented by the entry is initially activated for 
entering messages. 

- indicates that the station represented by the entry is not initially activated 
for entering messages. 

Entries may be both activated or deactivated for entering, accepting, or both 
entering and accepting, by means of various operator commands or by an ICHNG 
macro issued in an application program. When poUing is used as the method of 
invitation, only stations that are activated for entering are polled. 

Following the indicator in an entry are the invitation characters for the station. 
These will be either polling characters or an identification sequence. Invitation 
characters are generally assigned to a station when it is installed. For information 
on whether a particular station can be assigned identification or polling characters, 
consult the component description SRL for that type of station. Invitation 
characters are specified in transmission-code representations converted to hexade- 
cimal notation. (For conversion tables, see Appendix D .) Each group of invita- 
tion characters in a Ust must be of the same length. 

An invitation list entry might be coded as follows: 

NYC+E40D 

Here NYC is the name of an IBM 1050 terminal in New York City, + indicates 
that this entry is active for entering messages, and E40D is the IBM 1050 
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transmission-code representation of the polling characters B6 in hexadecimal 
notation. 

Because one operand of a macro is limited to 255 characters, TCAM provides a 
facihty to specify additional INVLIST entries if necessary. A comma placed as 
the last character of the last entry field; that is, 

INVLIST ORDER=( entry, entry, . . .entry, ) 

indicates a continuation of the macro. The next source statement would then be 
coded 

INVLIST ORDER=( entry, entry, . . . ) 

There is no limit (other than the maximum of 200 entries that may be specified) 
on the number of continuation statements used. 

The exact manner in which the INVLIST macro is coded depends upon the line 
configuration and upon station features. The following paragraphs describe the 
possible ways in which INVLIST may be coded. 

Nonswitched point-to-point or multipoint lines to stations using polling characters 
Issue one INVLIST macro for each such line, and code at least one entry for each 
station (active and inactive) on the Hne. Each entry should include the terminal 
name, the active or inactive entry indicator, and the poUing characters assigned to 
the terminal. If a terminal is to be polled more than once in one pass through the 
invitation Ust, specify more than one entry for this terminal — the terminal will be 
polled once for each active entry specified. To poll a specific component o| a 
terminal, specify the second polUng character, which identifies that component. 

Example 1 : 

The following INVLIST macro creates the required invitation Ust for a non- 
switched multipoint line having three IBM 1050s as terminals. 

LIST1 INVLIST ORDER=(NYC+E40D,BOS+E20D,NYC+E40D, 

PHI-E715 ) 

TCAM uses the invitation Hst created by this macro to poll the IBM 1050 termi- 
nals located in New York City (NYC), Boston (BOS), and (again) New York 
City, in that order. The New York City terminal is polled twice as often as the 
Boston terminal. The Philadelphia terminal (PHI) is inactive until activated by the 
operator control facility or by an ICHNG macro issued in an appHcation program. 
E40D, E20D, and E715 are the IBM 1050 transmission-code representations of 
the polling characters B6, A6, and CO, respectively, in hexadecimal notation. + 
means the terminal is initially active; - means the terminal is initially inactive. 

Example 2: 

The following INVLIST macro creates the invitation Ust for a nonswitched 
multipoint line having one BSC IBM 2780 and one BSC IBM 1 130, using the 
Auto Poll hardware feature. 

LIST2 INVLIST ORDER=( BALH-C2F62D , DET+32C42D ) , 

EOT=37 
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TCAM uses the invitation list created by this macro to autopoU an IBM 2780 
located in Baltimore (BAL) and an IBM 1 130 located in Detroit (DET), in that 
order. The transmission-code for the terminals being autopoUed is EBCDIC; the 
C2F6 and C4 are the hexadecimal-notation form of the EBCDIC representation 
of the polling characters B6 and D, respectively. The 2D ending each entry is the 
hexadecimal-notation form of the EBCDIC representation of the ENQ line- 
control character, which must be included with all BSC poUing sequences. The 32 
in the Detroit entry is the hexadecimal-notation form of the EBCDIC SYN 
character, used to pad the DET polling sequence to the length of the BAL se- 
quence. The EOT= operand presents the hexadecimal form of the EBCDIC EOT 
character; it must follow all entries in an INVLIST macro for autopoUed terminals 
using EBCDIC transmission code. 

Switched lines to terminals using polling characters 

Issue one INVLIST macro for each such line. Polling characters for all polled 
terminals assigned to a switched line (by means of each terminal's TERMINAL 
macro, described below) must be identical. Since all terminals assigned to the 
same line have the same polUng characters, it is necessary to code only one 
representative entry as the operand of the INVLIST macro for a line; this entry 
names any one of the terminals assigned to the Une, and gives the poUing charac- 
ters for all terminals assigned to the line. A + should be coded for each entry. If 
a TERMINAL macro with the operand UTERM= YES is issued for the line, code 
the name of that TERMINAL macro, rather than the name of a terminal, in the 
representative entry. 

Example: 

The following INVLIST macro creates the invitation list for a switched line having 
three polled IBM 1050 terminals (NYC, BOS, and PHI) assigned to it. 

LISTS INVLIST ORDER=( NYC+E40D ) 

Whenever one of the three terminals calls in (or is called), TCAM uses the poUing 
characters represented in hexadecimal notation by E40D to invite it to enter a 
message. E40D is the IBM 1050 transmission-code representation of the polling 
characters B6, in hexadecimal notation. 

Note that only one of the three terminals is used to create the entry in the invita- 
tion list. If this entry were inactive (that is, if - rather than + were coded), none 
of the three terminals assigned to the Une could enter messages. 

Switched lines to stations using ID sequences 

Issue one INVLIST macro for each such line. Code one entry for each ID se- 
quence assigned to one or more stations on the line, and code the CPUID= 
operand if the computer is assigned an ID sequence. Each ID sequence is entered 
in its transmission-code representation, converted to hexadecimal notation. No 
framing characters or quotes are used. A -f should be coded for each entry. 

If each station assigned to a switched line has its own unique ID sequence, then 
one entry is coded for each station. Each entry consists of the station name, the 
active or inactive entry indicator, and the ID sequence assigned to the station. 
(See Example 1 below.) 

If two or more stations assigned to a switched Une share the same ID sequence, 
then one entry is coded for each different ID sequence assigned to a station or 
stations on the Une. If a TERMINAL macro specifying UTERM= YES is issued 



Defining Terminal and Line Control Areas 1 5 



for the line, then each entry consists of the name of the TERMINAL macro, the 
active/inactive entry indicator, and an ID sequence. If no such TERMINAL 
macro is issued, then each entry consists of the name of a representative station 
using the ID sequence mentioned in this entry, the active/inactive entry indicator, 
and an ID sequence. (See Example 2 below. For guidance on when to code a 
TERMINAL macro using UTERM= YES, see the discussion of the TERMINAL 
macro.) 

If a switched station calls in and enters an ID sequence, TCAM uses the ID 
sequence to estabUsh the origin of messages entered by the station. If a switched 
station (one that is assigned a non-unique ID sequence and that is represented by 
an invitation-Hst entry specifying the name of a TERMINAL macro coded for a 
Une) calls in and fails to identify itself by means of an origin field in a message 
header, the station will not receive any messages during the call because TCAM 
does not know whose messages to send unless there are messages queued for the 
line. If a switched station (one that is assigned a non-unique ID sequence and that 
is represented by an invitation-list entry specifying the name of a representative 
station using the ID sequence) calls in and fails to identify itself by an origin field 
in a message header, during the call the station receives those messages queued for 
the station named in the invitation-list entry, even if the calHng station and the 
station named in the invitation-list entry are two different stations. 

If a switched station calls in and enters an ID sequence, TCAM searches for the 
ID sequence in the invitation list associated with the Une over which the station 
called in. If the ID sequence is not found in an entry in the invitation Ust for this 
Une, TCAM conducts a search of the invitation Usts for any lines in this line group 
that have a higher relative line number than that assigned to the line over which 
the station called in. TCAM searches these invitation lists according to ascending 
relative line number until either the ID sequence is found in a Ust or the invitation 
Ust for the highest-numbered Une in the line group has been searched. If the ID 
sequence is found, TCAM assumes that the station associated with that ID 
sequence in the invitation Ust is the caUing station, and maintains the connection. 
If the ID sequence is not found, TCAM breaks the connection with the calling 
station, thereby freeing the line. 

Example 1: 

The following INVLIST macro creates the invitation Ust for a switched line having 
three IBM 2770 terminals (named NYC, BOS, PHI) assigned to it. Each of these 
terminals is assigned a unique ID sequence; that for NYC is AA, that for BOS is 
BB, while that for PHI is CC. PHI is not to be initially eligible for entering data. 
The computer is assigned the ID sequence POKl. The stations use EBCDIC line 
code. 

LIST4 INVLIST ORDER=( NYC+-C1 C1 , BOS+C2C2 , PHI-C3C3 ), 

CPUID=IDFIELD 

Here ClCl, C2C2, and C3C3 are the EBCDIC transmission-code representa- 
tions of the ID sequences AA, BB, and CC, respectively, in hexadecimal notation. 
Somewhere within the same area of addressability in the MCP the following field 
is defined: 

IDFIELD DC X»04' 

DC X*D7D6D2F1' 
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Here, 04 is the hexadecimal length of the rest of the field. D7D6D2F1 is the 
EBCDIC representation of the ID sequence POKl, in hexadecimal notation. 

Example 2: 

The following INVLIST macro creates the invitation Ust for a switched Une having 
six IBM 1 130 stations assigned to it. Three of these stations are assigned the ID 
sequence BATCH 1, while the remaining three are assigned the ID sequence 
BATCH2. The computer is assigned the ID sequence RAL. The stations use 
EBCDIC transmission code. A TERMINAL macro with UTERM=:=YES speci- 
fied, named RELLN3, has been issued for this line. 

LIST5 INVLIST ORDER=( RELLN3+C2C1 E3C3C8F1 , 

RELLN3+C2C1E3C3C8F2 ), 
CPUID=IDADDR 

Here, C2C1E3C3C8F1 and C2C1E3C3C8F2 are the EBCDIC transmission- 
code representations of the ID sequences BATCH 1 and BATCH2, respectively, in 
hexadecimal notation. Elsewhere in the MCP the following field is defined: 

IDADDR DC X'03' 

DC X'D9C1D3' 

Here, 03 is the hexadecimal length of the rest of the field. D9C1D3 is the 
EBCDIC transmission-code representation of the ID sequence RAL, in hexadeci- 
mal notation. 

Switched or nonswitched contention lines to terminals not assigned ID sequences 

If only one station is assigned to the line, include the station name and the active 
or inactive indicator in the entry portion of the macro. If more than one station is 
assigned to the line, include the name of a representative station and the active or 
inactive indicator in the entry portion of the macro. For IBM 2740 Basic and IBM 
2780 stations for which equal priority is specified in the line group DCB macro, 
include the station name and the active or inactive indicator in the entry portion of 
the macro. 

Example: 

The following INVLIST macro creates the invitation Ust for a nonswitched line to 
an IBM 2740 Basic terminal in New York City (NYC). 

LIST6 INVLIST ORDER=(NYC+) 

Output-only lines to stations having no ID sequences assigned to them 
Issue one INVLIST macro to serve all such Unes; the name of this macro should 
be specified in the INVLIST = operand of the DCB macro for each output-only 
line group. No operand is coded for this INVLIST macro. (Stations having ID 
sequences assigned to them must appear as entries in the INVLIST macro for their 
line, regardless of whether or not the line is output-only.) 

Example: 

The following INVLIST macro creates the invitation list for all output-only lines 
to stations having no ID sequences assigned to them. 

LIST7 INVLIST 
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Selection 

Selection is the process by which contact is established between the computer and 
a station for the purpose of transmitting data from the computer to the station. 

As is the case with invitation, there are basically two forms of selection. One of 
these is used with contention stations (which may or may not be equipped with a 
feature permitting identification sequence exchange), the other involves transmis- 
sion by the computer of addressing characters (similar to poUing characters) to a 
station preparatory to sending the station a message. Response to the transmis- 
sion of these characters indicates whether the terminal can accept the message. 

The contention form of selection is similar to the contention form of invitation, 
described above. When the computer has a message to send to a contention 
station, it waits until the line is free of traffic and then seizes it; once it has control 
of the line, the computer merely sends the message to the terminal. 

When addressing characters are used in selection, the selection process is closely 
related to the polling form of invitation, described above. That is, the flow of 
messages to and from a station is controlled by the computer according to an 
orderly scheme. The nature of this scheme is discussed in the section 
Maintaining Orderly Message Flow. Addressing characters are defined in the 
TERMINAL macro. 

Constructing the Terminal Table 

In selecting a station or application program, TCAM uses information provided by 
TCAM macros at assembly time and stored in control areas. The control areas 
used in selection all depend upon the terminal table. The terminal table consists 
of blocks of information about each station and appHcation program; each such 
block is called a terminal entry . 

There are eight types of terminal entries: 

• A single entry in the terminal table defines a single station. A single entry is 
created by a TERMINAL macro; one such entry must be created for each 
station in the system that is not defined by a group or Hne entry (see below). 

• A group entry represents a group of terminals on a hne that have a group 
addressing feature (whereby all terminals on a multipoint line recognize ad- 
dressing characters, but only one of the terminals responds); specification of a 
single set of addressing characters results in simultaneous transmission of a 
message to all terminals in the group. If a terminal that is a member of a group 
is also to be addressed individually, or is to be polled, it must be represented by 
a single entry as well. A group entry is defined by a TERMINAL macro and is 
for output only. 

• A component entry defines a component of a station that may be addressed 
individually — forexample, a card reader or a printer on an IBM 1050 station. If 
more than one component of a station may be addressed individually, a compo- 
nent entry may be required for each. A component entry is defined by a 
TERMINAL macro. 

• A line entry defines a switched line that is used for input or input/output 
operations. The line entry is used to supply device characteristics for stations 
that call in on a switched Une before they identify themselves (by the origin 
field in a message header, as checked by an ORIGIN macro in the Message 
Handler), and for stations that call in and never identify themselves. The entry 
is defined by a TERMINAL macro specifying UTERM=YES. 

• A distribution list entry contains a list of pointers to single, group, cascade, or 
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process entries. When a message or FORWARD macro contains the list name 
as its destination code, TCAM sends the message by separate transmissions to 
all stations indicated by the Ust. Each station on the list must have a corre- 
sponding single or group entry in the terminal table. A distribution list entry is 
defined by a TLIST macro. 

• A cascade list entry contains a list of pointers to single, group, or process 
entries. When a message or FORWARD macro contains the list name as its 
destination code, the message is queued to be sent to that single valid station or 
opened process entry in the Ust that has the least number of messages queued 
for it. A valid station is one that is capable of accepting a message, and that is 
on a line for which the line group data set has been opened. If more than one 
valid station has the sniallest number of messages queued, the message is 
queued for the first in the Ust. If no station is vaUd or if all queues are of the 
same length, the message is queued for the first station in the list. A cascade 
entry is defined by a TLIST macro. 

• A process entry represents an application program. One process entry must be 
defined for each queue to which an application program can issue a GET or 
READ and at least one must be defined for all PUTs or WRITEs from the same 
application program. One open input or output DCB in the application pro- 
gram is associated with each process entry. A process entry is defined by a 
TPROCESS macro. 

• A logtype entry represents a queue of complete messages for a logging medium. 
A logtype entry is defined by a LOGTYPE macro. 

The size, structure, and contents of the terminal table depend upon information 
provided by the user through the TTABLE, OPTION, TERMINAL, TLIST, 
TPROCESS, and LOGTYPE macro instructions. These macros are described in 
this chapter. 

Macro instructions defining the terminal table are coded as a group. For an 
example of a coding sequence for a terminal table, see the chapter Putting the 
MCP Together. 
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TTABLE 



symbol 



LAST = name 



lVlAXLEN=integer 



OLTERIVI=ii 



The TTABLE macro 

• defines the start of a terminal table; 

• names the last entry in the table; 

• is required as the first macro defining the terminal table; 

• is issued only once. 

An operand of TTABLE specifies the name of the last macro issued in the section 
of code defining the terminal table; thus, TTABLE defines the beginning and end 
of the terminal table coding section. The TTABLE macro must be followed 
immediately by the macros defining the terminal table. 

TTABLE has the following format: 



Name 


Operation 


Operands 


[symbol] 


TTABLE 


LAST = name[ ,M AXLEN = integer] 
[,OLTERM=n] 



Function: Specifies the name of the macro and the name of 

the terminal name table (an internal table associated with the terminal table). 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the last entry in the terminal table (that is, the 
name of the last TERMINAL, TLIST, or TPROCESS macro coded). 
Default: None. This operand must be specified. 
Format: Must conform to the rules for assembler language symbols. 



Function: Specifies the number of characters in the name of the terminal table. 
Default: None. Specification optional. 
Format: An unframed decimal integer. 
Maximum: 8 

Notes: If this operand is omitted, the length of the last entry in the list is as- 
sumed. The operand is not necessary if the lengths of all terminal table entry 
names are the same, or if the last entry is the longest. 



Function: Specifies the number of dummy terminal name table entries to be 

allocated when using TOTE. See the description of TOTE in the section Using 

TCAM Service Facilities. 

Default: OLTERM=0. If zero dummy entries are allocated to TOTE, no remote 

station can be the control terminal or the alternate printer. 

Format: An unframed decimal integer. 

Maximum: 255 



20 OS/MFT and OS/MVT TCAM Programmer's Guide 



OPTION 



The OPTION macro 

• permits space to be reserved for an option field related to a station, component, 
line, or application program; 

• must be specified before any TERMINAL, TLIST, or TPROCESS macros; 

• is optional among the macros defining the terminal table. 

OPTION macros are issued as a group; in conjunction with the OPDATA= 
operands of the TERMINAL and TPROCESS macros they define the option 
table , a storage area containing option fields related to individual stations, compo- 
nents, lines, or application programs. Access to the option fields is gained by 
certain Message Handler routines that need source- or destination-related storage 
in order to perform their functions. Among the MH macros that invoke routines 
to gain access to the option fields are the following: STARTMH, INHDR, 
INBUF, INMSG, OUTHDR, OUTBUF, OUTMSG, COUNTER, ERRORMSG, 
FORWARD, LOCOPT, MSGLIMIT, PATH, and REDIRECT. To gain some 
insight into the function of option fields, the reader should turn to the individual 
discussions of these macros in the chapter De5/g«/>2g a Message Handler. 
User-written routines can also gain access to information in an option field. 

Taken together, the OPTION macros issued by a user define a complete set of 
option fields; all or part of this set may be assigned to a particular station, compo- 
nent, line, or application program by coding the OPDATA= operand of the 
TERMINAL or TPROCESS macro (see the example below). An OPTION macro 
merely gives an option field a name and describes the type and length of the field 
in assembler language format; an area of storage is neither initialized nor actually 
allocated for the field unless the field is specified for a particular station, compo- 
nent, line, or application program by means of the OPDATA= operand of the 
TERMINAL or TPROCESS macro. Up to 254 option fields, each of which may 
be as large as 255 bytes, may be defined in an MCP by OPTION macros. All or 
any part of the set of option fields may be allocated to each station, component, 
line, or application program represented by a terminal-table entry. For the set of 
option fields for a particular entry in the terminal table, the last option field must 
be within 254 bytes of the first. 

A new area of storage having the name and attributes specified by the OPTION 
macro defining an option field is assigned to each station, component, line, or 
application program whose TERMINAL or TPROCESS macro initiaUzes that 
field. Each TERMINAL or TPROCESS macro may initiaUze a field differently; 
hence different stations, components, lines, or application programs may be 
assigned option fields having identical names and attributes, but different con- 
tents. This feature allows the user to tailor the functions of a macro gaining access 
to an option field to meet the needs of a particular station, component, line, or 
application program. For example, the COUNTER macro maintains a count of 
messages or message segments received from or sent to a station. This counter is 
located in an option field for that station. If the OPTION macro for this field is 
named COUNT, and if the COUNTER macro names COUNT as the field in 
which the counter should be maintained, then a separate counter will be main- 
tained for each station that uses the OPDATA= operand of the TERMINAL 
macro to initialize COUNT. 

A macro coded in an inheader, inbuffer, or inmessage subgroup handUng messages 
entered by stations on a line gains access to the specified option field for the 
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opfldname 



typelength 



Station that entered the message being processed. (If the originating station is 
unknown because it called in on a switched line and failed to identify itself, access 
to specified option field for the line entry associated with this line is gained.) A 
macro coded in an outheader, outbuffer, or outmessage subgroup handling 
messages destined for stations on a line gains access to the specified option field 
for the station that is to accept the message being processed. A macro coded in an 
outheader, outbuffer, or outmessage subgroup handling messages destined for an 
application program, gains access to the specified option field associated with the 
process queue to which the GET or READ macro that is moving this message to 
the appHcation program is directed. A macro coded in an inheader, inbuffer, or 
inmessage subgroup handling messages being received from an application pro- 
gram gains access to the specified option field for the process entry associated 
with the DCB named in the PUT or WRITE macro. 

OPTION has the following format: 



Name 


Operation 


Operand 


opfldname 


OPTION 


typelength 



Function: Specifies the name of the option field. 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the type and length of the option field. 

Default: None. This operand must be specified. 

Format: Standard assembler language format (for example, H, CL8, AL3). All 

assembler language codes may be used. However, B, C, P, X, and Z must be 

coded with a length attribute (for example, CL5, BL4). Duplication factors are 

not allowed; that is, ABC OPTION 3DL5 is an invalid macro. 

Notes: When the option field is used in conjunction with the FORWARD, 

ERRORMSG, or REDIRECT macro, a character string of length n must be 

specified, where n is the length in bytes of the data in the OPDATA= operand of 

the TERMINAL or TPROCESS macros that initialize the fields. 

If used with counter, typelength should be specified as H, since this macro requires 
a half word field on a half word boundary. 

If used with INBUF, INHDR, INMSG, OUTBUF, OUTHDR, OUTMSG, PATH, 
or MSGLIMIT macros, typelength should specify a one-byte field (for example, 
FLl, ALl). No boundary alignment is required. 

If used with STARTMH, typelength will specify a one- or four-byte field, depend- 
ing upon which STARTMH operand names the option field. 

Points to remember: 

• OPTION macros, if used, must be issued as a group and must immediately 
follow the TTABLE macro. 

• The order in which OPTION macros are arranged determines the order in 
which initiaUzation data must be specified in the OPDATA= operand of the 
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TERMINAL or TPROCESS macro. If a field specified by an OPTION macro 
is not to be defined for a particular station, component, line, or application 
program, then a comma should be coded in place of the data for this field in the 
OPDATA= operand (but trailing commas should not be coded). 
OPTION macros should be arranged so as to prevent waste of storage space in 
the option table. For example, if three OPTION macros are coded 

AA OPTION FL1 
AB OPTION CL4 
AC OPTION H 

the halfword specification for the AC field causes the assembler to perform 
boundary alignment. Since the AC field may not already be on a halfword 
boundary, one byte of storage area in the option table may be wasted for each 
terminal for which these option fields are defined. To conserve storage space, 
the above macros should be coded as follows: 



AC OPTION H 
AA OPTION FL1 
AB OPTION CL4 

If four OPTION macros are coded 

BA OPTION F 
BB OPTION CL1 
BC OPTION H 
BD OPTION CL1 

two bytes of storage area in the option table will be wasted for each station 
after the first for which these option fields are defined. To conserve storage 
space, the macros should be coded: 



BA OPTION F 
BC OPTION H 
BB OPTION CL1 
BD OPTION CL1 

• In coding an OPTION macro, the user must specify the type and length of the 
option field to be generated. This information is contained in the discussion of 
the individual macro that gains access to the option field. 

Example: 

In the following example, the TTABLE macro defines the beginning and end of 
the terminal table section of the Message Control Program. The OPTION mac- 
ros, which are a part of this section of code, define fields in the option table that 
are used by the COUNTER, MSGLIMIT, REDIRECT, ERRORMSG, and PATH 
macros. 





TTABLE 


LAST=:PROC 


COUNT 


OPTION 


H 


MSGLMT 


OPTION 


FL1 


REDRECT 


OPTION 


CL3 


ERRMSG 


OPTION 


CL4 


PATHSW 


OPTION 


FL1 



TTABLE defines PROC as the name of the last entry in the terminal table. The 
I OPTION macros define an 11 -byte optional area for entries in the terminal table. 

The optional area consists of five fields: 
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• COUNT defines a halfword for decimal data to be used by the COUNTER 
macro. 

• MSGLMT defines one byte for decimal data to be used by the MSGLIMIT 
macro. 

• REDRECT defines a character string consisting of three bytes naming the 
terminal; this data is used by the REDIRECT macro. 

• ERRMSG defines a character string consisting of a four-byte terminal name; 
this data is used by the ERRORMSG macro. 

• PATHSW defines one byte for eight binary path switches to be tested by 
various delimiter macros. 

If the OPDATA= operand of a TERMINAL macro were coded 

OPDATA=( 0,0, NYC, PITT, 3 ) 

an 1 1-byte storage area would be set aside in the option table for use by MH 
macros in handUng messages to and from that terminal. The COUNT and 
MSGLMT fields would initially contain 0, the REDRECT field would contain 
NYC, the ERRMSG field would contain PITT, and the PATHSW field would 
contain 3. 

If the OPDATA= operand of another TERMINAL macro were coded 

OPDATA=( ,, NYC, PITT) 

a 7 -byte storage area would be set aside in the option table for use by MH macros 
in handUng messages to and from that terminal. Only the REDRECT and 
ERRMSG fields would be created. 

Note that for an option field to be created for any particular terminal, two condi- 
tions must be satisfied: 

1 . An OPTION macro defining the field must be issued. 

2. The field must be initiaUzed in the OPDATA= operand of the TERMINAL 
macro for that terminal. If a comma is coded in place of a field in the 
OPDATA=s operand, no space is set aside for that field. If the OPDATA= 
operand of a TERMINAL macro is omitted, no option fields are set aside for 
that terminal. 
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TERMINAL 



The TERMINAL macro 

• creates a single, group, or line entry in the terminal table; 

• specifies the type of queuing to be used (that is, queuing by Une or queuing by 
terminal)*; 

• specifies the addressing characters to be used in addressing a station; 

• specifies when the computer is to initiate contact with switched stations; 

• specifies how often the computer is to initiate contact with switched stations; 

• designates secondary operator control stations; 

• specifies initial data for the option table; 

• specifies an alternate destination for messages sent to the station for which this 
TERMINAL macro is issued; 

• overrides the buffer size specified by the BUFSIZE= operand of the Une group 
DCB, for output only; 

• specifies blocking factors to be used for inserting control characters in outgoing 
messages destined for this station, when a MSGFORM macro is executed in an 
outheader subgroup handling such messages; 

• is required for each single or group station or line entry in the TCAM system. 

The TERMINAL macro causes an EBCDIC name of a station or line, and infor- 
mation associated with the station or line, to be included as an entry in the termi- 
nal table. If a single station or component is involved, TERMINAL produces a 
single entry in the terminal table. If a group of stations having the group address- 
ing feature is involved, TERMINAL produces a group entry. If a Une is involved, 
TERMINAL produces a line entry. 

One TERMINAL macro should be coded for: 

L Each station (whether switched or nonswitched) that can accept messages, and 
for some terminals that can only enter messages (see Coding the TERMINAL 
Macro for a Line below). 

2. Each group of nonswitched terminals equipped with the group addressing 
feature. Terminals can only accept messages under the group addressing 
feature; they cannot enter messages. Each terminal in the group that can also 
enter messages, or that can be addressed separately, must also be represented 
by a single entry. 

3. Each switched line to stations that do not uniquely identify themselves after 
calling the computer. 

For guidelines on coding the TERMINAL macro for a Une and for a component, 
see the next two sections of this chapter. 

TERMINAL macros for stations on a line must be issued together, and the groups 
of TERMINAL macros for each Une in a line group must be in ascending relative 
Une sequence. 

When TERMINAL macros are issued for the individual components of a station, 
the macros for the components must immediately follow that for the station. 
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See Appendix G. Device-Dependent Considerations , for particular specifications 
for the 

1030 Station; 

2260 Display Station (remote); 

2740 with Station Control or Station Control and Checking feature; 

2740 with the Transmit Control or Transmit Control and Checking feature; 

2740 Basic Terminal; 

2740 Model 2 Communications Terminal; 

2741 Communication Terminal; 
2770 Data Communications System; 
2790 Data Communications System; 
IBM 3270 Information Display System 
IBM 3670 Brokerage Communication System 
IBM 3780 Data Communication Terminal 
BSC stations; 
AT&T83B3 stations. 

TERMINAL has the following format: 



Name 


Operation 


Operands 


symbol 


TERMINAL 


QBY= (T ) 

,DCB=dcbname 
,RLN= integer 
,TERM=type 
,QUEUES=form 
[,DIALNO=(chars )] 
iNONEj 
[,ADDR=chars] 
[,LEVEL=(integer,...)] 
[,CLOCK=time] 
[,CINTVL=integer] 
[,BUFSIZE=integer] 
[,ALTDEST=entry] 
[,BFDELAY=ipteger] 
[,NTBLKSZ=(blocksize,subblocksize)] 
[,TBLKSZ=integer] 
[,OPDATA=(data,...)] 
[,RETRY=mteger] 
[,LMD=lYESl] 

(no/ 

[,MB= jYESa 
(NO/ 
[,SECTERM=(YES)] 

\NO f 
[,FEATURE=fATTN \ 

Inoattn/ 

[,COMP= (YES)] 
|NO / 
[,UTERM=/YESn 

|no f 
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symbol 



Function: Specifies 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 

Notes: This name can appear in an origin or destination field of a message 

header. SYSCON may not be used. 

If more than one TERMINAL macro is specified for the same buffered station (by 
coding two TERMINAL macros, with different names, for the same station), 
message segments may become intermixed during sending or receiving operations. 
Furthermore, a text segment may be treated as a header segment. For these 
reasons, coding more than one TERMINAL macro for the same buffered station 
is not a recommended procedure, unless the TERMINAL macros are coded for 
components rather than for the station itself. 



QBY= 



{1} 



Function: Specifies the type of message queuing 
Default: None. This operand must be specified. 
Format: T or L. 

Notes: T specifies that outgoing messages are to be queued by station; that is, all 
messages for a given station on a Hne are sent in priority order before any mes- 
sages for other stations on that line are sent (except for 2770 stations for which 
BFDELAY= is coded; messages are sent to these stations a buffer at a time). T 
should be specified for switched stations, and must be specified for stations using 
TCAM's buffered-terminal support or for a TCAM terminal that includes logical 
messages. For a more complete discussion of queuing by station, see Maintaining 
Orderly Message Flow in this chapter. L specifies that outgoing messages are to 
be queued by line; messages for all stations on the Hne are sent on a first-ended 
first-out basis within priority groups. If L is specified for stations on a switched 
line, when contact is made with a station on that Hne, all messages on the queue 
are sent to that station, regardless of what station they are intended for. For a 
more complete discussion of queuing by line, see Maintaining Orderly Message 
Flow in this chapter. This operand is ignored if the TERMINAL macro is coded 
for a component or for a line (that is, the UTERM= operand of the TERMINAL 
macro must either be omitted or must specify NO). 



DCB:=dcbnanie 



RLN= integer 



Function: Specifies the name of the data control block for the line group in which 

the station is included. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols. 



Function: Specifies the relative line number, within the Hne group, of the access 

line over which the computer and the station communicate. 

Default: None. This operand must be specified. 

Format: An unframed decimal integer. 

Maximum: 255 

Notes: For a discussion of how relative line numbers are assigned, see DD 

Statements for a Line Group . For a switched station on a line for which no 

TERMINAL macro coded for a line is issued and for which no message priority is 

used, any access line in the group may be specified. When the computer calls a 
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TERIVl=type 



QUEUES=foriii 



Station assigned to a switched line, it attempts to make the call using the line 
whose relative line number is specified. If that line is unavailable, the Hne whose 
relative line number is greater than that specified by integer is examined; this 
process is repeated until a free Hne is found or until all lines in the group that have 
relative Une numbers higher than the integer specified for this station have been 
examined. If all higher-numbered Unes in the hne group are unavailable, the 
station is not dialed at this time. Dialing is postponed until a suitable line is 
available. 

If message priority is used for switched Hnes for which no TERMINAL macro 
coded for a line is issued, this operand should be coded RLN= 1. 



Function: Specifies the terminal type. 
Default: None. This operand must be specified. 

Format: This operand may be replaced by any of the following values. 1030, 
1050, 1060, 226L (2260 Local), 226R (2260 Remote), 226C (2260 Control), 
2265, 274 A (nonswitched Basic 2740 Model 1), 274B (switched 2740 Model 1), 
274C (nonswitched 2740 Model 1 with Station Control), 274D (nonswitched 
2740 Model 1 with Station Control and Checking), 274E (switched 2740 Model 1 
with Transmit Control and Checking), 274F (nonswitched 2740 Model 1 with 
Checking), 274G (switched 2740 Model 1 with Checking), 274H (switched 2740 
Model 1 with Transmit Control), 2741 (2740 Model 2 with Checking), 274J 
(2740 Model 2 without Checking), 2741, 2760, 277A (polled 2770), 277B 
(non-polled 2770), 278A (polled 2780), 278B (non-polled 2780), 373A (polled 
3735), 373B (non-polled 3735), 7770, 113A (polled 1130), 113B (non-polled 
1 130), 202A (polled Model 20), 202B (non-polled Model 20), 83B3, 1 15A 
(Western Union Plan 115A outstations on a nonswitched network), 3335 (AT& T 
33/35 Dial), WTTY (World Trade telegraph terminals), S36B (non-polled 
System/360). 327C (3270 Remote Control), 327L (3270 Local), 327R (Remote 
Clustered), 327S (3270 Standalone Remote), 367A (Polled 3670), 367C 
(Broadcast 3670), BSCl, BSC2, BSC3. 

BSCl, BSC2, and BSC3 are convenient ways of specifying a category of termi- 
nals. BSCl represents point-to-point, nonswitched terminals (113B, 180B, 202B, 
373B, S03B, S36B). BSC2 represents point-to-point switched terminals (same 
devices as BSCl). BSC3 represents multipoint terminals (113A, 180A, 202A, 
2972 (2970 Terminal), 363A (3670 Terminal), 367A, S03A, S36A (S/360). 
Notes: The TERM= operand can be written either of two ways. 



TERM=202A or TERM=BSC3 



Function : Specifies 

where the message queues are to be 

maintained. 

Default: None. This operand must be specified. 

Format: DR, DN, MO, MN, or MR. 

Notes: For a discussion of this topic, see Message Queues Data Sets . 

If queuing is by terminal, this operand must be specified for all TERMINAL 
macros for a station on the line. If queuing is by line, this operand must be 
specified for the first TERMINAL macro coded for a station on the line, but may 
be omitted for subsequent TERMINAL macros for stations on the line. 



28 OS/MFT and OS/M VT TCAM Programmer's Guide 



DIALNO= (chars ) 
(NONE ) 



ADDR=chars 



DR specifies reusable disk queues. 

DN specifies nonreusable disk queues. 

MO specifies main-storage-only queues. 

MR specifies main-storage queues with backup on reusable disk. 

MN specifies main-storage queues with backup on nonreusable disk. 

If MO is specified, the distribution Ust, multiple routing, and REDIRECT facilities 
should be used with care, since one extra buffer is required to accommodate every 
destination other than the original destination. 

If the form of data set specified by this operand does not correspond to a related 
message queues data set specified in the DCB, TCAM terminates abnormally. 

If MO, MR, or MN is specified, the MSUNITS= operand of the INTRO macro 
must specify a nonzero integer; otherwise, the TERMINAL macro does not 
assemble properly and an MNOTE is generated. 



Function: Specifies the telephone number of the station. 
Default: None. Specification optional. 

Format: chars or NONE, chars is a decimal field with no framing characters. 
Notes: This operand tells TCAM whether a station is on a switched or a non- 
switched Une, and it must be specified for switched stations, chars is the tele- 
phone number of the station. 

DIALNO=chars must be specified if the CINTVL= operand of this macro is 
specified. DIALNO=NONE specifies that this station is on a switched line, but 
the computer may not initiate calls to it. DIALNO=NONE must be specified if 
the transmission control unit for the line over which contact is to be established 
with the station does not have the Auto Call feature and should be specified if 
Inward WATS lines are to be used to best advantage. The user also must specify 
all optional features (for instance. Auto Call and Auto Answer) at system genera- 
tion time for lines or their related terminals. 

If this operand is omitted, the station for which this TERMINAL macro is coded 
is assumed to be on a nons witched line. 



Function: Specifies the addressing characters for the station, or specifies the 

end-to-end control sequence for switched or nonswitched point-to-point 2770 or 

2780 stations. 

Default: None. Specification optional. 

Format: Unframed hexadecimal equivalent of the appropriate transmission-code 

representation. 

Notes: Addressing characters are used by the central computer to inform a 

station that the computer wishes to send it a message. For information on the 

addressing characters for a specific station, see the hardware manual for that 

station. 

If a station is assigned an ID sequence rather than addressing characters, this 
operand is not coded; the ID sequence is entered in the invitation list (see the 
discussion of the INVLIST macro). 
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LEVEL= (integer,...) 



CLOCK =time 



CINTVL=:integer 



This operand must also specify the end-to-end control sequence for a point-to- 
point 2770 or 2780 station. For information on the end-to-end control sequence, 
see the appropriate hardware manual. The end-to-end control sequence is speci- 
fied by writing the equivalent of the appropriate transmission-code representation, 
and must be immediately preceded by the STX line-control character and immedi- 
ately followed by the ETB line-control character. 



Function: Specifies the permissible priority levels that may be used in the header 
of a message destined for this station. 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum: 255 

Notes: The levels must be specified in increasing order. For instance, if the 
messages being sent to a certain station can have priorities of 1, 9, or 1 1, the 
LEVEL = operand for this station would be coded LEVEL =(1,9,1 1). If queuing 
is by Une rather than by terminal, the priority levels specified in the first 
TERMINAL macro coded for a station on the Une will apply to all stations on that 
line; in this case, the LEVEL = operand of subsequent TERMINAL macros for 
the same line is ignored. 

For more information on message priority, see the discussion of the PRIORITY 
macro and Message Priority and Queuing in this chapter. 



Function: Specifies the time of day that the computer should initiate contact with 
a switched station. 

Default: None. Specification optional. 

Format: Two decimal integers for the hours, immediately followed by two 
decimal integers for the minutes. Framing characters may not be specified. 
Maximum: 2359 (that is, 23 for the first field, 59 for the second). 
Notes: If this operand is specified, CINTVL= must be omitted and DIALNO= 
must specify the dial digits to be used. If CLOCK= and CINTVL= are both 
omitted, the computer does not periodically initiate contact with this switched 
station. When CLOCK= is specified, the only time that the switched station will 
be sent messages is when the computer initiates contact with it (at the time of day 
specified by this operand). If the station calls in at any time other than that 
specified by this operand, it may enter messages but will not be sent any messages 
by the computer (except that a station locked to an appUcation program will get its 
lock responses). This operand is used to take advantage of low toll times. If there 
are no messages queued for the station at the appropriate time, TCAM will dial 
the station and invite it to enter messages. 



Function: Specifies the number of seconds following which the computer should 

initiate contact with a switched station, if neither the station nor the computer 

called the other during this period. 

Default: None. Specification optional. 

Format: Unframed decimal integer. 

Maximum: 65535 

Notes: The interval is restarted at the termination of each call from the station, 

or when the computer calls the station to send its messages. If CINTVL= is 

specified, DIALNO= must also be specified, and CLOCK= must be omitted. 

The first interval starts when the line group data set for this Une is opened. This 

operand can be used to take advantage of Outward WATS. 



30 OS/MFT and OS/MVT TCAM Programmer's Guide 



BUFSIZE=integer 



ALTDEST=eiitry 



BFDELAY=integer 



Function: Specifies the buffer size, in bytes, for outgoing messages destined for 

this station, and overrides the BUFSIZE= operand of the Hne group DCB macro. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 

Notes: If this operand is omitted, the buffer size specified in the Une group DCB is 

used. 



Function: Specifies the alternate destination to which a message on a reusable 

disk queue is sent at the time the zone containing the message is serviced for 

reuse. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols, and specify 

the name of any single, group, or process entry in the terminal table capable of 

accepting messages. Framing characters must not be specified. 

Notes: See Reusable Disk Queues for a description of servicing for reuse. When 

the destination queue defined by a TERMINAL macro is reorganized, unsent 

messages on the queue are placed on the destination queue specified by the 

ALTDEST= operand. ALTDEST= may specify the original destination as well 

as any other vaUd destination. If the ALTDEST= operand is omitted, messages in 

a reusable disk queue may be written over and lost to the system with no error 

indication being made. This operand is ignored unless either QUEUES =DR or 

QUEUES = MR is specified in this TERMINAL macro. 



Function: Specifies the number of seconds of delay to be used before another 
message block is sent to a buffered station (to avoid sending another message 
block while the hardware buffer is still emptying the previous block of data). 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum : 65535 

Notes: integer should specify the average time needed to empty the hardware 
buffer. This may be computed from the number of characters in the hardware 
buffer and the rate at which characters are transferred from the buffer to the 
terminal component. 

This operand must be coded for IBM 2740 Model 2 and multipoint IBM 2770 
stations and must not be coded for any other station. For information on 
TCAM's buffering feature, see Transmission Priority for Nonswitched Polled 
Stations Using TCAM's Buffering Feature in this chapter. 

The BFDELAY= operand must either be included in all TERMINAL macros for 
stations on the same line, or omitted from all TERMINAL macros for stations on 
the Une. When this operand is coded, queuing by station and send priority should 
also be specified. If stations using a buffer delay are intermixed with nonbuffered 
stations on the same line (this can be done because BSC stations are compatible), 
BFDELAY=0 should be specified in the TERMINAL macros for the nonbuffered 
stations. The BFDELAY= operand should not be specified for start-stop or BSC 
stations on switched or point-to-point lines. 
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NTBLKSZ=(blocksize, subblocksize) 



Function: Specifies blocking factors for outgoing messages in non transparent 

mode directed to this station. 

Default: None. Specification optional. 

Format: Unframed decimal integer. 

Maximum: For blocksize , 65535. For subblocksize ,255. 

Notes: blocksize is the number of bytes in each block of data in nontransparent 

mode for messages directed to this station, when the MSGFORM macro is coded 

in the outheader subgroup handling these messages. 



blocksize is used when LC=OUT is specified in the STARTMH macro to indicate 
where BOB or ETB line-control characters are to be inserted in outgoing mes- 
sages. If a block size of 100 were specified, an EOB or ETB would be inserted 
after every 100 characters in the message, provided that the message were handled 
by an outheader subgroup that contains a MSGFORM macro. The value specified 
here may be overridden by coding the BLOCK = operand of the MSGFORM 
macro; if the blocksize suboperand is omitted from the TERMINAL macro, 
MSGFORM may still be used to specify the blocking factor. The character 
inserted is not considered part of the block. 

subblocksize is the number of bytes in each subblock of data in nontransparent 
mode for messages directed to this BSC station. It is used when LC=OUT is 
specified in the STARTMH macro to indicate where ITB line-control characters 
are to be inserted in outgoing messages. If a subblock size of 100 were coded, an 
ITB would be inserted after every 100 characters in the message, provided that 
the message were handled by an outheader subgroup that includes a MSGFORM 
macro. The value specified here may be overridden by coding the SUBBLOCK= 
operand of the MSGFORM macro; if the subblocksize suboperand is omitted 
from the TERMINAL macro, MSGFORM may still be used to specify the number 
of bytes per subblock. The ITB inserted is not considered part of the block. 



{ 
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TBLKSZ=integer 



OPDATA=(data,...) 



Function: Specifies the number of bytes in each block of data for outgoing 
messages in transparent mode. 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum: 65535 

Notes: The appropriate line-control sequence is transmitted after each number of 
bytes of data specified by integer , provided that the MSGFORM macro is coded 
in the outheader subgroup handling this message, and provided that 
SENDTRP=YES is coded in MSGFORM. The value specified here may be 
overridden by coding the BLOCK= operand of the MSGFORM macro. If the 
TBLKSZ= operand is omitted from the TERMINAL macro, MSGFORM may 
still be used to specify the blocking factor for outgoing messages in transparent 
mode. 



Function: Specifies the actual data to be inserted in the set of option fields 
assigned to this station (see the discussion of the OPTION macro), and also 
specifies which option fields are not to be created for this station. 
Default: None. Specification optional. 

Format: The maximum length and type of data specified for each option field 
must correspond to the length and type specified by the OPTION macro that 
defines the field, and the order in which the data for each field is specified must 
correspond to the order in which the OPTION macros are specified. Framing 
characters are not used. 
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Notes: When specifying option fields for a particular station, the user may omit 
the last several option fields defined by OPTION macros by merely closing the 
parenthesis after the data for the last field he wishes to define. A comma is used 
to: 

1. Delimit the data for each field; 

2. Indicate that no data is specified for the first or an intermediate field defined by 
an OPTION macro; 

3. Indicate that the OPDATA operand is to be continued (if specified immediately 
preceding the right parenthesis — see note below). 

The user must specify either data and a comma, or a comma alone for the first and 
each intermediate field (except the last) that is specified by an OPTION macro 
(with one exception — see the note below). A comma alone is coded if a field 
other than the last is not to be defined for this station. If the last field is not to be 
defined, no data is coded for the field and the comma is also omitted. Framing 
characters (X or C and quotes) are not coded. 

Example: 

Assume that four OPTION macros have been coded. If the user wants to specify 
all four fields for a particular station, line, or application program, he would code 
the OPDATA= operand of the TERMINAL or TPROCESS macro as follows: 

,OPDATA=( fieldl , f ield2 , f ield3 , f ield4 ) 

where fieldl , fieldl , fields , and field4 represent the actual initial data to be 
inserted into each of the four option fields. If only fieldl and field4 are to be 
implemented for this station, line, or appHcation program, the user would code 

,OPDATA=( fieldl , , , f ield4 ) 
If only fieldl , fieldl , and fields are to be implemented, the user would code 

,OPDATA-( fieldl , f ield2 , f ield3 ) 
If only fieldl is to be implemented, the user would code 

,OPDATA=( fieldl ) 

Because one operand of a macro is limited to 255 characters, TCAM provides a 
facility to specify additional OPDATA= parameters if necessary. A comma 
placed as the last character of the OPDATA= operand — that is, 

,OPDATA=( data, data, . . .data, ) 

indicates a continuation of the OPDATA = operand. The next source statement 
would then be coded 

symbol TERMINAL OPDATA=( data, . . . ) 

where symbol is the name specified on the TERMINAL macro that specified the 
continuation. 

There is no limit (other than the number of option fields defined) on the number 
of continuation statements that may be used. 
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RETRY=integer 



LMD= f yes) 



ivib=(yes ) 

JNOI 



Function: Specifies the maximum number of times the CPU is to retry dialing a 

switched station. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than zero. 

Maximum: 255 

Notes: This operand is required if the RETRY macro is specified in the inmessage 

subgroup. This TERMINAL macro also must specify the DIALNO= operand and 

either the CLOCK= or the CINTVL= operand. 

A HOLD macro with bit 26 specified in the mask should be coded in the outmes- 
sage subgroup so that no messages will be lost if the retry count is reached without 
the CPU having initiated contact with the switched station. However, if the 
CLOCK = operand is specified, the user must assure that messages are released 
before the specified time expires again in order for them to be sent to the station 
when the time does expire. 



Function: Specifies whether individual logical messages entered by this station 
may be included in multiple physical transmissions. 
Default: LMD=NO 
Formal: YES or NO 

Notes: YES indicates that any individual logical message entered by this station 
may be in more than one transmission sequence (that is, if part of a logical 
message is entered in a transmission sequence, the remainder of the message may 
be included in the station's next transmission sequence — two or more transmission 
sequences may be used to enter this message). This allows an incoming logical 
message to be larger than the physical limitations imposed by the source station. 
No intervening data may be included between the beginning and the end of the 
logical message. YES must be coded if this station is a 2715. 

If this operand is omitted, or if NO is specified, logical messages entered by this 
station must be entered in their entirety in a single transmission sequence. 

Logical messages are discussed in Handling Logical Messages in the chapter 
Defining the Message Handler. 



Function: Specifies whether mid-batch recovery is to be performed when a 

permanent text error is encountered in a multiblock message to or from a station. 

Default: MB=NO 

Format: YES or NO. 

Notes: YES indicates that mid-batch recovery is to be performed. If NO is 

specified, or if this operand is omitted, an entire message is canceled when a text 

error is encountered. 
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For incoming operations, the STARTMH macro must specify STOP = YES, and 
the inmessage subgroup must contain a CANCELMG macro that specifies 
LEVEL=BLK. 

For outgoing operations, also include the LEVEL =BLK operand on the HOLD 
macro and the QBY=T operand on the TERMINAL macro. 

MB = YES is the default for both switched and buffered stations; the MB= 
operand need not be specified for a switched or buffered station. Queuing by 
terminal is required for mid-batch recovery on both input and output operations. 



feature=Jattn ) 
i noattn i 



Function: Allows for the disposition of CPU transmission interrupted by IBM 
1050 and IBM 2741 terminals. 

Default: FEATURE = NOATTN Specification of this operand is optional. 
Format: ATTN or NOATTN. 

Notes: ATTN or NOATTN may be specified for both the IBM 1050 and the IBM 
2741 terminals equipped with an attention key. If ATTN or NOATTN is speci- 
fied for a terminal other than a 1050 or 2741, the entry is ignored. 

ATTN specifies that the station receiving data from the CPU can interrupt the 
CPU during the transmission. The user can provide for the disposition of the 
interrupted message by using functional macros in his MH. If this entry is omit- 
ted, and if the attention key is active for this station, interrupted CPU transmis- 
sions are handled as errors with no recovery for the interrupted message. 



secterm=Jyes ) 



Function: Specifies whether this station may be considered a secondary operator 

control station. 

Default: SECTERM=NO 

Format: YES or NO. 

Notes: If YES is specified, operator commands will be recognized, acted upon, 

and the appropriate response returned to the station. The station for which 

SECTERM=YES is specified must be on a nons witched line and must be able to 

both enter and accept messages. If a station other than the system console is to be 

the primary operator control station, SECTERM= YES must be specified for that 

station's TERMINAL macro. 



COMP= JYESl 



Function: Specifies whether or not this TERMINAL macro is being used to define 

a component of a station defined by another TERMINAL macro. 

Default: COMP=NO 

Format: YES or NO. 

Notes: If this operand is coded COMP= YES, then the TERMINAL macro is for 

a component. If the operand is omitted or COMP=NO is coded, then the macro 

is not for a component. 

For guideUnes on coding this operand, see Coding the TERMINAL Macro for 
a Component in this chapter. 



{ 
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UTERM= /YES\ 

mi 



Function: Specifies whether or not this TERMINAL macro is being used to define 
a Une entry in the terminal table. 
Default: UTERM=NO 
Format: YES or NO. 

Notes: If this operand is coded UTERM=YES, then the TERMINAL macro is 
for a line. If the operand is omitted, or if UTERM=NO is coded, then the 
TERMINAL macro is either for a station or a component — if coded for a station, 
this TERMINAL macro also must specify the QBY= operand. 

For information on coding this operand, see Coding the TERMINAL Macro 
for a Line in this chapter. 

Coding the TERMINAL Macro for a Component 

If the COMP= operand of a TERMINAL macro is coded COMP=YES, then the 
TERMINAL macro is one defining a component of a station defined by another 
TERMINAL macro. A TERMINAL macro need be issued for a component only 
if messages may be directed to more than one component of a station by means of 
appropriate addressing characters. If addressing characters are not used, a 
TERMINAL macro for a component is unnecessary. If a message can be sent to 
only one component of a terminal assigned addressing characters, that component 
may be specified by coding the appropriate addressing characters in the ADDR= 
operand of the TERMINAL macro for the terminal. For an IBM 1050 terminal 
assigned addressing characters, for example, the second addressing character 
identifies the component that is to receive the message. If only one component is 
to receive messages, that component's selection character may be entered as the 
second addressing character in the ADDR= operand of the TERMINAL macro 
for the terminal, and no TERMINAL macro need be issued for the component. If 
more than one component of a station is to be specifically addressed by means of 
addressing characters, then one or more component TERMINAL macros must be 
issued; these should immediately follow the TERMINAL macro for the station to 
which the components belong. 

The following operands of the TERMINAL macro are meaningful if the macro is 
issued for a component: 

ADDR=chars 

specifies the addressing characters for this component. 

ALTDEST=entry 

specifies the alternate destination to which a message on a reusable disk queue is 
sent at the time the zone containing the message is serviced for reuse (see 
Reusable Disk 12"^"^'^ for ^i description of this servicing). Any terminal, compo- 
nent, or process entry for a device capable of accepting messages may be speci- 
fied. If the operand is omitted, messages in a reusable disk queue may be written 
over and lost to the system with no error indication being made. 
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SECTERM=\ YES 



J YES I 
] NO ) 



Specifies whether repUes to operator commands entered at this station are to be 
sent to this component. If so, this component must be represented in the invita- 
tion Ust for this Une. If the station is polled, the operator command must have 
been entered in response to polling characters associated in the invitation list with 
an entry having the same name as the name of this terminal entry. (However, the 
two entries having the same name need not refer to the same device — the polUng 
characters could poll a card reader, for example, while the addressing characters 
might address a printer). 

NTBLKSZ=(blocksize,subblocksize) 

specifies blocking factors for outgoing messages in nontransparent mode directed 
to this station, blocksize and subblocksize have the same meanings as those 
described above in the discussion of the TERMINAL macro for a station. 

TBLKSZ= integer 

specifies the number of bytes in each block of data for outgoing messages in 
transparent mode directed to this component. This operand is similar to the 
TBLKSZ= operand for the TERMINAL macro for a station, described above, 
and may be overridden by coding the BLOCK = operand of the MSGFORM 
macro, and specifying SENDTRP=YES in MSGFORM. 

BUFSIZE=integer 

overrides the buffer size specified by the BUFSIZE= operand of the line group 
DCB macro, but only for buffers containing outgoing messages destined for this 
component. If this operand is omitted, the buffer size specified in the Hne group 
DCB macro is used. 

OPDATA=(data,...) 

specifies the actual data to be inserted in the set of option fields assigned to this 
component (see the discussion of the OPTION macro), and also specifies which 
option fields are not to be created for this component. The description of the 
OPDATA= operand of the TERMINAL macro for a station also applies to the 
OPDATA= operand of the TERMINAL macro for a component. 

COMP=jYES( 
fNO S 

specifies whether this TERMINAL macro is for a component. COMP=YES 
indicates that this TERMINAL macro is for a component. 

Coding the TERMINAL Macro for a Line 

A TERMINAL macro whose UTERM= operand is coded UTERM= YES causes 
information to be included in the terminal table for a line to switched stations that 
do not uniquely identify themselves when calling the computer. 

As a general rule, a switched Une should have its own TERMINAL macro if any 
stations that do not always uniquely identify themselves call the computer on that 
line. If all stations calling in on a switched line always uniquely identify them- 
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selves, no TERMINAL macro is required for that line. The following considera- 
tions apply when deciding whether a particular switched line requires its own 
TERMINAL macro (see also Figure 1, which summarizes these considerations). 

1. A TCAM audio line (that is, a line connected to an IBM 7770 Audio Response 
Unit, Model 3) requires its own TERMINAL macro. 

2. A switched line to BSC stations that are all assigned unique ID sequences does 
not require its own TERMINAL macro. For such a Une, the user should enter 
each station's name and ID sequence, and the CPU ID sequence, in the appro- 
priate operands of the INVLIST macro for the line (see the discussion of the 
INVLIST macro). 

3. If none of the stations on a line ever dial the computer, the line needs no 
TERMINAL macro. Terminal names and invitation characters are coded in the 
INVLIST macro (see the discussion of the INVLIST macro). 

4. For a switched line to stations other than those described in (2) and (3) above, 
code a TERMINAL macro specifying UTERM=YES unless all messages 
entered by stations on the line have origin fields in their message header and 
are processed by a Message Handler subgroup containing an ORIGIN macro 
(see the discussion of the ORIGIN macro). For lines to stations that enter only 
messages having origin fields, see (5). When a TERMINAL macro is coded for 
a line, the name of the macro is entered together with the invitation characters 
for stations on the line in the appropriate operand of the INVLIST macro for 
the line (see the discussion of the INVLIST macro). 

5. For a switched line to stations other than those described in (2) and (3), if all 
messages entered on the line have vaUd origin fields in their message headers 
and are processed by a Message Handler subgroup containing an ORIGIN 
macro, then a TERMINAL macro may be specified for that line at the option 
of the user. If the TERMINAL macro is specified, the user must enter its name 
as part of the entry operand of the INVLIST macro for the line; otherwise the 
name of a TERMINAL macro for a station on the line is entered as part of the 
INVLIST entry. In either case, one INVLIST entry is coded for each series of 
invitation characters used by a station on the line (see the discussion of the 
INVLIST macro). 

In order to decide whether to code a TERMINAL macro for a Une under Case 5, 
the user must first understand the function of the ORIGIN macro and the origin 
field of the message header (discussed in the chapter Designing the Message 
Handler ) and must also understand the function of the OPTION macro (discussed 
in the present chapter). Then he should consider the following paragraphs. 

The TERMINAL macro has an optional OPDATA= operand. If a TERMINAL 
macro is coded for a switched line, when a station on that line dials the computer, 
access is gained to the option fields associated with the line entry, and these fields 
are possibly modified by Message Handler macros until an ORIGIN macro is 
encountered in the Message Handler. In addition, messages may be routed to the 
line entry; any station calling in will receive these messages until it is identified by 
an origin field checked by an ORIGIN macro. 

The ORIGIN macro establishes the identity of the calling station; once identity 
has been estabUshed, the option fields associated with the terminal entry for the 
station calling in are made available and possibly modified by Message Handler 
macros, and messages queued for the station are sent to it in the manner described 
in the section Transmission Priority in Defining Terminal and Line Control 
Areas . 
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Figure 1 . Determining whether a TERMINAL Macro Should Be Coded for a Switched Line 



Thus, if a user assigns no option fields to the stations on a switched Une, or if he 
does assign option fields but issues his ORIGIN macro in the Message Handler 
subsections handhng incoming messages before he issues any macros that modify 
option fields, he is safe in omitting the TERMINAL macro for that Une (but he 
may code the macro if he wishes to direct messages to any station caUing in on the 
Une). Otherwise, a TERMINAL macro specifying UTERM=YES should be 
coded for the line. AU TERMINAL macros for Unes in a line group must be 
arranged according to ascending relative Une number. The TERMINAL macro 
for a particular Une must immediately precede aU TERMINAL macros for stations 
on that Une. 

Example: 

The TERMINAL macros for three switched Unes in a line group, where each Une 
has three terminals associated with it, would be arranged in the foUowing order: 

• TERMINAL macro for relative line 1 (UTERM= YES) 

• TERMINAL macro for a terminal on line 1 

• TERMINAL macro for a second terminal on Une 1 

• TERMINAL macro for a third terminal on Une 1 

. TERMINAL macro for relative line 2 (UTERM= YES) 

• TERMINAL macro for a terminal on line 2 

• TERMINAL macro for a second terminal on line 2 

• TERMINAL macro for a third terminal on line 2 

. TERMINAL macro for relative line 3 (UTERM= YES) 

• TERMINAL macro for a terminal on Une 3 

• TERMINAL macro for a second terminal on line 3 

• TERMINAL macro for a third terminal on line 3 
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It may be that some lines in a line group have TERMINAL macros coded for them 
and others do not. In this case, arrange the TERMINAL macros for the stations 
on the Hnes in groups according to ascending relative line number, and place each 
TERMINAL macro for a line immediately in front of the group of TERMINAL 
macros for stations on that line. 

Example: 

The TERMINAL macros for three switched lines in a line group, where each Une 
has two terminals associated with it, and line 2 has no TERMINAL macro coded 
for it, would be arranged in the following order: 

. TERMINAL macro for relative Hne 1 (UTERM=YES) 

• TERMINAL macro for a terminal on line 1 

• TERMINAL macro for another terminal on line 1 

• TERMINAL macro for a terminal on line 2 

• TERMINAL macro for another terminal on Une 2 

• TERMINAL macro for relative Une 3 (UTERM=YES) 

• TERMINAL macro for a terminal on line 3 

• TERMINAL macro for another terminal on Une 3 

The following operands of the TERMINAL macro are relevant when the macro is 
specified for a Une: 

DCB=dcbname 
RLN=integer 
QUEUES=form 
TERM=type 
BUFSIZE=integer 
ADDR= chars 
OPDATA=data 
UTERM= (yes) 
INO j 

The DCB=, RLN=, and TERM= operands are the same as those given above for 
a TERMINAL macro for a station. 

For station-initiated calls that require a response, the ADDR= operand is coded 
only when the calUng station does not identify itself by an origin field in a message 
header. A caU from such a station would either: 

(a) cause the originating station to accept messages directed to the Une entry, 

(b) cause a response message to be sent back to the originating station by a 
MSGGEN macro in the Message Handler, or 

(c) place the originating station in lock mode (see the description of the LOCK 
macro) to await a response message from an application program. 

The ADDR= operand of the TERMINAL macro for a station must be coded if 
any messages are to be queued for that station. If the ADDR= operand of the 
TERMINAL macro for a line is coded, aU stations on the line must have identical 
addressing characters. 

The OPDATA= operand specifies the data to be inserted in the set of option 
fields assigned to this line. The operand is coded in the same way as the 
OPDATA= operand of a TERMINAL macro for a station. 

The QUEUES = operand is required, whether or not any messages are to be 



'f directed to the line entry as a destination. 
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When a station on this line dials the computer, access is gained to the option fields 
assigned to the line and the fields are modified by Message Handler macros until 
an ORIGIN macro in the Message Handler establishes the identity of the calling 
station. Once identity is established, the option fields assigned to the station 
calling in are updated by macros following the ORIGIN macro in the Message 
Handler. When the computer calls a station, only the option fields assigned to the 
station may be updated. 

The BUFSIZE= operand is optional and, if used here, overrides the BUFSIZE= 
operand of the line group DCB macro for messages directed to the line entry as a 
destination. 

The UTERM= operand, when coded UTERM=YES specifies that this 
TERMINAL macro is for a line. If the operand is omitted or coded 
UTERM=NO, this TERMINAL macro is not for a line. 
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TLIST 



The TLIST macro 

• defines a cascade list entry or distribution list entry in the terminal table; 

• is optional among macros defining the terminal table. 

The TLIST macro causes the name of a Ust of single, group, or process entries in 
the terminal table, together with information about the entries in the list, to be 
included as an entry in the terminal table. 

A distribution or cascade Ust consists of the names of single, group, or process 
entries in the terminal table. One TLIST macro must be specified for each Ust to 
be created. Stations cannot enter messages using either a distribution or a cascade 
list. 

When a message contains the name of a distribution Ust as a destination code, 
TCAM sends the message by separate transmissions to each station or appUcation 
program indicated by an entry in the Ust. Each entry in the Ust must have a 
corresponding single, group, or process entry in the terminal table. When a 
message contains the name of a cascade list as a destination code, TCAM places 
the message on the destination queue for that valid destination in the Ust that has 
the fewest messages waiting to be sent to it. If several destinations have the same 
number of messages, the message is queued for the first such destination Usted. 

The TLIST macro provides the initial contents for aU fields in the Ust entry. 



Name 


Operation 


Operands 


symbol 


TLIST 


TYPE= |DlLIST=(entry,entry,...) 



symbol 



TYPE= 



{?} 



Function: Specifies the name of the Ust. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies whether the Ust is a distribution or a cascade Ust. 

Default: None. This operand is required. 

Format: D or C. 

Notes: C specifies a cascade Ust. D specifies a distribution list. 



LIST= (entry ,entry,...) 



Function: Specifies the actual entries in the distribution Ust or cascade Ust being 

created. 

Default: None. This operand is required. 

Format: Each entry is the name of a single, group, process, or cascade list entry 

in the terminal table. If TYPE=D, at least two entries must be specified. If 

TYPE=C, only one entry is required. 

Notes: The name of a distribution Ust entry in the terminal table may not be 
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specified as an entry in a distribution list. If ttie list being created is a distribution 
list, it may contain the name of one or more cascade list entries. If it is a cascade 
list, it may not contain the name of a cascade list entry. 

Because of the limitation of 255 characters in a macro operand, a faciUty is 
provided to specify additional TLIST entries if necessary. A comma placed as the 
last character of the entries operand indicates a continuation of the Ust. The next 
source statement would then be coded: 

symbol TLIST LIST=( entry, . . . ) 

where symbol is the TLIST name as specified on the previous TLIST macro that 
indicated the continuation. There is a limit of 32767 entries in a distribution or 
cascade Ust. 



< 



44 OS/MFT and OS/MVT TCAM Programmer's Guide 



TPROCESS 



The TPROCESS macro 

• serves as part of the interface between the MCP and an application program; 

• creates a terminal table entry for a queue associated with an application pro- 
gram; 

• is optional among macros defining the terminal table. 

The TPROCESS macro causes the name of a queue for an application program 
and associated information to be included as an entry in the terminal table. The 
entry produced is a process entry. 

One TPROCESS macro must be included for each destination queue to which an 
application program can direct a GET or READ macro, and at least one must be 
included for each process entry to which a PUT or WRITE macro may be 
directed. 

An operand of the TPROCESS macro specifies the name of a process control 
block (PCB), which is used to establish communication between a Message 
Handler and application programs. (The PCB is created by coding a PCB macro.) 

Another operand of TPROCESS enables the user to specify one alternate destina- 
tion to which the message may be sent in certain circumstances. 

The user may specify that checkpointing of the application program is to be 
synchronized with that of the Message Control Program. Synchronization of OS 
with TCAM checkpoints is discussed in the chapter Writing TCAM-Compatible 
Application Programs. 

The user also specifies the initial contents of the option fields for the process entry 
in the terminal table. 

The TPROCESS macro helps connect an application program to the Message 
Control Program. The GET and PUT or READ and WRITE macros issued in an 
application program each specify the name of a data control block created by a 
DCB macro issued in the application program. The DCB macro specifies (by its 
DDNAME= operand) a DD card. The QNAME= parameter of the DD card 
names a process entry. The pcbname operand of the TPROCESS macro creating 
this entry specifies a process control block. The MH= operand of the PCB macro 
creating the process control block specifies the Message Handler that handles 
messages directed to and received from the application program. 
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TPROCESS has the following format: 



procname 



PCB=pcbname 



QUEUES=form 



Name 


Operation 


Operands 


procname 


TPROCESS 


PCB=pcbname[,QUEUES=form] 
[,ALTDEST=entry] 
[,CKPTSYN=/YES\] 
INOf 
[,DATE=4YES n 

Ino ] 
[,secterm= jyes/] 

JNOJ 
[,RECDEL=delimiter] 
[,LEVEL= (integer,...)] 
[,OPDATA=(data,...)] 

[,qback4yes(] 



Function: Specifies the name of the process entry in the terminal table. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Notes: The name must be specified and must be the same as that entered in the 

QNAME= parameter of the DD statement associated with the DCB macro for an 

application program. 



Function: Specifies the name of the process control block that defines buffers, 

etc., to handle messages queued to this process entry. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The process control block is created by a PCB macro. All TPROCESS 

macros issued for the same application program must have the same PCB. 



Function: Specifies where the message queues containing messages for the applica- 
tion program are to be maintained (for GET/READ operations only). 
Default: None. Specification optional. 
Format: DR, DN, MO, MR, or MN. 

Notes: DR specifies reusable disk queues. DN specifies nonreusable disk queues. 
MO specifies main-storage-only queues. MR specifies main-storage queues with 
reusable disk backup. MN specifies main-storage queues with backup on nonreus- 
able disk. If the form of data set specified by this operand does not correspond to 
a related message queues data set defined by a DCB macro, the TCAM system 
terminates abnormally. By omitting the QUEUES = operand, the user specifies 
that this process entry is for PUTs or WRITEs from an application program (that 
is, do not code the QUEUES= operand for PUT/WRITE operations). 



If MO, MR, or MN is specified, the MSUNITS= operand of the INTRO macro 
must specify a nonzero integer; otherwise, the TPROCESS macro does not 
assemble properly and an MNOTE is generated. 
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ALTDEST=entry 



Function: If this process entry is for GETs or READs issued by an application 
program, this operand specifies the alternate destination to be sent when the zone 
containing the message is being serviced for reuse. If this process entry is for 
PUTs or WRITES from an application program, this operand specifies the destina- 
tion to which replies to operator commands issued by the application program are 
sent. 

Default: None. Specification optional. 

Format: The name of any single, group, or process entry in the terminal table. 
Notes: The entry specified may be the one created by the TPROCESS macro, 
preventing the message from being discarded from a reusable queue. If this 
operand is omitted for a GET or READ process entry, the message may be 
overlaid in a reusable queue and lost to the system. The operand is ignored unless 
QUEUES=DR or QUEUES=MR is specified for the TPROCESS macro. 

For a PUT or WRITE entry, the destination may be a station named by a 
TERMINAL macro, or it may be an appHcation program represented by a 
TPROCESS macro. 



ckptsyn=|yes) 
|no| 



Function: Specifies whether the destination queue to which the application 
program directs its GETs or READs is to be purged of serviced messages at 
restart. 

Default: CKPTSYN=NO 
Format: YES or NO. 

Notes: CKPTSYN= YES specifies that no purging of the queue is to be per- 
formed. If an OS checkpoint of the appHcation program is used in synchroniza- 
tion with the TCAM checkpoint, CKPTSYN=YES should be specified. If this 
operand is omitted, the queue is scanned and updated at restart. When synchroni- 
zation is not specified, operation following restart with scan resumes with the first 
unserviced message for the queue (a message is considered serviced when a GET 
or READ is issued for the next message from the queue and that next message is 
placed on the queue). The first unserviced message is determined in the scan of 
the message queue done at restart time. When not using synchronization with an 
OS checkpoint, it is necessary to check for one dupUcate message upon restart 
(that is, the message being processed when failure occurred). 



For more information on TCAM's checkpoint facility, see the chapter Using 
TCAM Service Facilities . Coordination of OS and TCAM checkpoints is dis- 
cussed in the chapter Writing TCAM -Compatible Application Programs . 



DATE=fYES\ 
JN0| 



Function: Specifies whether the date and time of each message received for the 
process entry are to be recorded. 
Default: NO 
Format: YES or NO 

Notes: When a message is received for the application program, TCAM records 
the date and time. When the appUcation program issues a GET or a READ 
macro, TCAM places the recorded date/time and the source of the message in the 
area specified by the DTSAREA= operand of the TPDATE macro. 
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SECTER1V1=\ YES 
NO 



Function: Specifies whether the application program may be considered a sec- 
ondary operator control station (so that operator commands may be sent to 
TCAM from the application program by using a PUT or WRITE macro). 
Default: SECTERM=NO 
Format: YES or NO. 

Notes: This operand is meaningful only if this process entry is associated with a 
PUT or WRITE macro, and is ignored if coded for a process entry associated with 
a GET or READ macro. If this PUT/WRITE process entry is to be the primary 
operator control station, SECTERM=YES must be specified for the entry. 



RECDEL=delimiter 



LEVEL=(iiiteger,...) 



Function: For a process entry associated with a GET or READ macro this 
operand specifies a one-byte, nonzero hexadecimal value used to delimit a record 
for the application program. For a process entry associated with a PUT or 
WRITE macro, this operand specifies a value to be inserted at the end of each 
variable-length record returned from an application program by means of a PUT 
or WRITE macro specifying the DCB associated (by coding the QNAME= 
operand of its DD card) with the process entry. 
Default: None. Specification optional. 
Format: A single, unframed hexadecimal character. 

Notes: This character may be inserted periodically into a TCAM buffer by coding 
a MSGEDIT macro with D AT A= DELIMIT for a process entry associated with a 
GET or READ. If the RECFM= operand on the input DCB macro specified by a 
GET or READ macro in the application program specifies V, VB, or U, and if the 
OPTCD= operand does not have the U suboperand coded in it, the application 
program GET or READ considers this character to be a record delimiter. The 
delimiter specified by RECDEL= may be included by the user in the incoming 
message, or may be inserted by means of a MSGEDIT macro. 

For a process entry associated with a PUT or WRITE macro, TCAM automatical- 
ly inserts the value at the end of each variable-length record. For other than 
variable-length records, this operand is meaningless. 



Function: Specifies the permissible priority levels that may be used in the header 
of a message enqueued on this process queue. 
Default: None. Specification optional. 

Format: Each integer is a decimal integer. Tht integer,... values must be speci- 
fied in ascending order. 
Maximum: 255 

Notes: If this operand is omitted, all messages sent to the application program by 
this process entry are assumed to have zero priority. If the messages being sent to 
the application program through this process entry can have, for example, priori- 
ties of 1, 9, or 11, the LEVEL= operand would be coded LEVEL=(1,9,11). 

For more information on message priority, see the discussion of the PRIORITY 
macro and Message Priority in this chapter. 



OPDATA=(data,...) 



Function: Specifies the actual data to be inserted in the set of option fields 
assigned to this process entry (see the discussion of the OPTION macro), and also 
specifies which option fields are not to be created for this process entry. 
Default: None. Specification optional. 



i 
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Format: The maximum length and type of data specified for each option field 
must correspond to the length and type specified by the OPTION macro that 
defines the field. The order in which the OPTION macros are specified must 
correspond to the values of data specified in this operand. 
Notes: A comma is used to: 

1. Delimit the data for each field; 

2. Indicate that no data is specified for the first or an intermediate field defined by 
an OPTION macro; 

3. Indicate that the OPDATA= operand is to be continued (if included immedi- 
ately preceding the right parenthesis — see below). 

The user must specify either data and a comma, or a comma alone for the first and 
each intermediate field (except the last) that is specified by an OPTION macro 
(with one exception — see the note below). A comma alone is coded if a field 
other than the last is not to be defined for this Une. If the last field is not to be 
defined, no data is coded for the field and the comma is also omitted. Framing 
characters (X or C and quotes) are not coded. 

When specifying option fields for a particular process entry, the user may omit the 
last several option fields defined by OPTION macros by merely closing the 
parentheses after the data for the final field he wishes to define. 

Example: 

Assume that four OPTION macros have been coded. If the user wants to specify 
all four fields for a particular station, Une, or application program, he would code 
the OPDATA= operand of the TERMINAL or TPROCESS macro: 

,OPDATA=( fieldl , field2, field3, f ield4 ) 

where fieldl , field! , fields , and field4 represent the actual initial data to be 
inserted into each of the four option fields. If only fieldl and field4 are to be 
implemented for this station, line, or application program, the user would code 

,OPDATA=( fieldl , , ,field4 ) 
If only fieldl , fieldl , and field3 are to be implemented, the user would code 

,OPDATA=( fieldl , f ield2, f ieldS ) 
If only fieldl is to be implemented, the user would code 

,OPDATA=( fieldl ) 

A message processed by an application program and then sent to a destination 
station must be handled by two sets of incoming and two sets of outgoing MH 
subgroups. Macros issued in the incoming subgroups handUng messages from a 
station update the option fields assigned to that station. Macros issued in the 
outgoing subgroups handling messages for the application program update the 
option fields assigned to the process entry associated with the GET or READ 
macro that obtains the messages for processing. Macros issued in the incoming 
subgroups handling messages from an application program update the option 
fields assigned to the process entry associated with the PUT or WRITE macro that 
returns messages from the application program to the MCP. Macros issued in 
outgoing subgroups handling messages being sent to a destination station update 
the option fields assigned to that station. (For a description of which Message 
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QBACK= 



J yes) 



Handler subgroups are required when there is an apphcation program, see 
Message Flow through a Message Handler in the chapter Designing a Mes- 
sage Handler . For a discussion of the interface between the MCP and the apphca- 
tion program see the introduction to Writing TC AM -Compatible Application 
Programs .) 

Because the operand field of a macro is limited to 255 characters, TCAM provides 
a facility to specify additional OPDATA= parameters if necessary. A comma 
placed as the last character of the OPDATA= operand — that is, 

,OPDATA=( data, data, . . .data, ) 

indicates a continuation of the OPDATA= operand. The next source statement 
would then be coded 

symbol TPROCESS OPDATA=( data, . . . ) 

where symbol is the process entry name as specified on the TPROCESS macro 
that specified the continuation. There is no limit (other than the number of option 
fields defined) on the number of continuation statements used. 



Function: Specifies whether the application program may issue the QRESET 
macro. 

Defauh: NO 

Format: QBACK=YES or QBACK=NO 

Notes: QBACK=YES causes the Queue Reset Executor module to be loaded into 
the MCP region and the allocation of a 258 byte work area in the MCP region. 
For information about TCAM's QRESET facility see Writing TCAM Compati- 
ble Application Programs. 



< 
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typename 



dcbname 



BUFSIZE=size 



LOGTYPE 



The LOGTYPE macro 

• initializes TCAM's logging facility; 

• may not be omitted if TCAM's logging facility is to be used for logging com- 
plete messages, and is unnecessary if segments are logged; 

• if coded, must be specified among the macros defining the terminal table and 
must not be the last such macro. 

The LOGTYPE macro initiaUzes TCAM's logging facility by specifying: 

1. The name of the data control block for the log data set, 

2. The buffer size used to handle messages to be logged, 

3. The location of the data set (on disk or in main storage). 

TCAM's logging facility is discussed in Using TCAM Service Facilities . The 
description of the LOG macro contains information on when LOGTYPE should 
be specified. 

A LOGTYPE macro must not be coded as the last macro defining the terminal 
table. No more than one LOGTYPE macro should be coded for a log data set. 



Name 


Operation 


Operands 


typename 


LOGTYPE 


dcbname, BUFSIZE=size 
,QUEUES=form 



Function: Specifies the name of the LOGTYPE macro and is the same 

as the typename operand of a LOG macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



Function: Specifies the name of the data control block for the log data set. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This name must be the same as the name of the DCB macro specifying the 

log data set. 



Function: Specifies the size of the buffers to be used to handle messages destined 

for the logging medium. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 



QUEUES=fonn 



Function: Specifies where the messages are to be queued while awaiting transfer 

to the logging medium. 

Default: None. This operand is required. 

Format: DR, DN, MO, MR, or MN. 
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Notes: DR specifies reusable disk queues. 

DN specifies nonreusable disk queues. 

MO specifies main-storage-only queues. 

MR specifies main-storage queues with reusable disk backup. 

MN specifies main-storage queues with backup on nonreusable disk. 

If MR or DR is specified, the original destination is automatically designated as 
the alternate destination for zone reorganization (see Reusable Disk Queues in 
the chapter Z)e/m/Aig the MCP Data Sets). Unlike the TERMINAL and 
TPROCESS macros, there is no ALTDEST= operand for the LOGTYPE macro. 

Maintaining Orderly Message Flow 

Thus far, this chapter has described how to define control areas needed by TCAM 
for line control, and how contact is estabUshed for the purposes of invitation and 
selection. This section describes how TCAM maintains an orderly message flow 
between the central computer and remote stations. 

Among the factors influencing the flow of messages within a TCAM system are 
message priority and queuing, transmission priority, and whether incoming logical 
messages are being handled. Message priority refers to the order in which 
messages are sent over a Une or to an application program. Priorities are assigned 
to individual messages by the user through his use of a priority field in the message 
header, a PRIORITY macro, and the type of queuing specified by the QBY= 
operand of the TERMINAL macro. Transmission priority refers to the relative 
order in which messages are sent to and received from a station or stations on a 
Une. The transmission priority (send, equal, or receive) for a nonswitched station 
is specified by the CPRI= operand of the line group DCB macro. For switched 
stations, CPRI=S (indicating send priority) must always be specified. If logical 
messages are being used, see Handling Logical Messages in the chapter 
Designing the Message Handler. 

These are not the only factors influencing TCAM message flow; two others are 
the manner in which calls are made between the computer and a switched station, 
and the system interval. The remainder of this chapter is devoted to discussions of 
all of these factors. 



Message Priority and Queuing 



To determine how to assign priorities to messages in a TCAM system, see the 
descriptions of the PRIORITY macro and of the LEVEL= operand of the 
TERMINAL and TPROCESS macros. In this section, we shall be concerned with 
a practical description of what message priority means in a TCAM system. 

This order depends upon three variables: 

• whether queuing is by line or by terminal; 

• the relative order in which the messages are received at the destination queue; 

• what priorities the messages are assigned. 

Messages whose destinations are stations may be queued by destination terminal 
or by destination line. The user specifies the type of queuing he wants by the 
QBY= operand of the TERMINAL macro. When outgoing messages are queued 
by line, one message queue is created for a line, and messages destined for all 
stations on the line are placed on this queue. (The incoming group of a Message 
Handler generally determines the destination of a message by a FORWARD 
macro.) Messages are taken off the queue and sent to stations on the line on a 



{ 



52 OS/MFT and OS/MVT TCAM Programmer's Guide 



first-ended first-out (FEFO) basis within priority groups. That is, messages on 
the queue that have a high message priority (as specified in the message header or 
assigned by a PRIORITY macro) are sent before messages having a low priority. 
When messages have the same priority, the one whose final segment arrived at the 
queue first will be sent out first, and the others will be sent out in the order in 
which their final segments arrived at the queue. (An example of queuing by line is 
given below.) 

Advantages of Queuing by Line 

• Queuing by line permits transmission of messages by priority on a line basis to 
stations on a multipoint nonswitched line; that is, all messages of a given 
priority on the queue are transmitted before any messages of a lower priority, 
whether or not the higher-priority messages are destined for two different 
stations on the line. 

• Queuing by line takes less storage space than queuing by terminal. If queuing is 
by line rather than by terminal, at least 65 bytes are saved for each station after 
the first on a line, plus about 28 bytes per station after the first for each priority 
level specified beyond one. 

Disadvantages of Queuing by Line 

• Queuing by line results in switching between stations on the line rather than 
maintaining connection with a station. 

When outgoing messages are queued by terminal, one message queue is created 
for each station on a line. All messages queued for a given station are sent before 
any messages queued for other stations on the line. Messages on a queue are sent 
to a station on first-ended first-out (FEFO) basis within priority groups. The first 
message on a queue is the message whose last segment arrived at the queue before 
the last segment of any other message arrived at the queue. High-priority mes- 
sages are sent before low-priority messages; when two messages on a queue have 
equal priority, the one whose final segment arrived at the queue earUest is sent 
first. For a multipoint line, the relative order in which queues of messages are 
transmitted is also determined on a FEFO basis; the queue containing the message 
whose incoming transmission over the line was completed first will be sent before 
any other queue for a station on that line. 

Queuing by terminal must be specified for switched stations and for buffered 
terminals. If switched stations were queued by line, a station that called in would 
receive not only its messages, but those for all other stations in the line group as 
well. 

Messages destined for an application program are placed on a queue for that 
program and are removed from it as if they were messages queued by terminal; 
that is, they too are sent to the application program on a FEFO basis within 
priority groups. 

Advantages of Queuing by Terminal 

• Queuing by terminal permits transmission of messages by priority on a station- 
by-station basis. All messages in a given queue for a station on a Une are 
transmitted before any messages in other queues for the remaining stations on 
the line are transmitted, whether or not the other queues contain messages 
having priorities higher than those for the messages being transmitted. Thus, 
messages for the same station are sent as a group. 
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Disadvantages of Queuing by Terminal 

• Queuing by terminal takes more storage space than does queuing by line. 

The orders of sending described above are disrupted when a message segment for 
which the INITIATE macro has been executed arrives at a destination queue; such 
a segment is treated as if it were a completed message having the highest priority 
on the queue, and it is sent before any other message on that queue is sent. In 
addition, no message on the queue may be sent until all segments of the message 
for which INITIATE was executed have arrived at the queue and been sent to 
their destination. (See the description of the INITIATE macro.) 

Examples: 

A multipoint nonswitched Une on which are located the following three terminals 
(each name given corresponds to the symbol field of the TERMINAL macro 
defining that terminal): NYC, BOS, RAL. Nine messages arrive from various 
remote stations, or perhaps from an application program; these messages are to be 
routed to the three terminals on this line. Messages 1 through 9 are completely 
enqueued on a destination queue in the following temporal order: 

1 for NYC 

2 for NYC 

3 for BOS 

4 for RAL 

5 for RAL 

6 for BOS 

7 for NYC 

8 for RAL 

9 for RAL 

Assume first that queuing is by line, and that all messages have the same message 
priority. In this case, the messages are sent out in the same order that they were 
enqueued on the destination queue for the line: 1, 2, 3, 4, 5, 6, 7, 8, 9. 

Now, assume that queuing is by terminal and that all nine messages have the same 
message priority. In this case, the messages are queued 

. 1,2, 7 for NYC 

• 3, 6 for BOS 

. 4,5, 8, 9forRal 

and are sent out: 1, 2, 7, 3, 6, 4, 5, 8, 9. 

Next, assume that messages 1, 5, and 9 have a message priority of 10; that mes- 
sages 2, 4, and 7 have a message priority of 30; and that messages 3, 6, and 8 have 
a message priority of 60. 

The messages will be queued by line or by terminal (depending upon which is 
specified in the TERMINAL macros) as if they all had the same priority. The 
order in which they are sent, however, differs from the case in which all messages 
have the same priority. 

If queuing is by line, the messages are sent in the order 3, 6, 8, 2, 4, 7, 1, 5, 9. 

If queuing is by terminal, the messages are sent in the order 2, 7, 1, 3, 6, 8, 4, 5, 9. 
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Transmission Priority 



Note the following points: 

• When messages for stations on a multipoint line are queued by terminal, the 
order in which the groups of messages queued for the individual stations on the 
line are transmitted depends on when the last segment of the first message on 
each individual queue arrives at the queue. In the above example the last 
segment of the first message on the queue for NYC arrived at its queue before 
the last segment of the first message on the queue for BOS arrived at its queue, 
and the last segment of the first message on the queue for BOS arrived at its 
queue before the last segment of the first message arrived on the queue for 
RAL. Therefore, all messages queued for NYC are transmitted before any 
message queued for BOS is transmitted, and all messages queued for BOS are 
transmitted before any message queued for RAL is transmitted. 

• When messages for stations on a multipoint Une are queued by terminal, the 
order in which the messages queued for an individual station are transmitted is 
determined by two rules: 

1 . All messages having a high message priority are transmitted before any 
message having a low message priority is transmitted. 

2. When messages have equal message priorities, the message whose final 
segment arrived at the queue first is sent first, the message whose final 
segment arrived at the queue second is sent second, etc. 

When these two rules are in effect, messages are said to be sent out on a 
first-ended-first-out (FEFO) basis within priority groups. 

Messages for stations on point-to-point lines, whether switched or non- 
switched, are also transmitted on a FEFO basis within priority groups. 
(Remember that switched Hnes are considered to be point-to-point, and that 
queuing by terminal should always be specified for switched lines.) 



Transmission priority refers to the relative order in which messages are sent to and 
received from the stations on a line. Transmission priority is specified on a Une 
group basis by the CPRI= operand of the line group DCB macro. 

Transmission priority has a different meaning for each of the following four 
configurations of stations: 

1 . Polled stations (unbuffered) on a nonswitched point-to-point or multipoint 
line; 

2. Buffered polled stations on a nonswitched multipoint line; 

3. Contention stations on a nonswitched point-to-point line; 

4. Stations on a switched Une. 

TCAM considers a buffered station to be one for which the BFDELAY= ope- 
rand of the TERMINAL macro is coded. A special scheme for transmitting 
outgoing messages is implemented for such a station (see the description of the 
BFDELAY= operand of TERMINAL). A station may be defined as buffered 
using the BFDELAY= operand even though no delay is ever taken. 

Transmission Priority for Nonswitched Polled Stations 

For such stations, the user may specify that sending has priority over receiving (by 
coding CPRI=S in the line group DCB macro), that receiving has priority over 
sending (CPRI=R), or that sending and receiving have equal priority (CRPI=E). 
The meaning of these priorities depends upon whether the line is being polled 
under the control of the TCAM program polUng scheme, or under the control of 
the Auto PoU hardware feature. 
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TCAM Program Poll: When this scheme is used, TCAM polls all stations 
designated as active in the invitation Ust for an active line. In poUing, TCAM 
begins with the first active station in the Ust, and invites it to enter a message by 
sending its polling characters. If the station has a message to enter, it responds by 
entering the message, following which TCAM polls it again. 

If receiving has priority over sending, the cycle of poUing and entering is repeated 
until the first station has no more messages to enter. When TCAM receives a 
negative response to polling from the first active station in the list, it proceeds to 
the second active station in the Ust, and poUs it. TCAM continues to poU the 
second station until the station indicates that it has no more messages to enter; 
TCAM then poUs the third station. TCAM proceeds through the Ust in this 
fashion until a negative response to polling is received from the last station in the 
list. At this time, TCAM observes the invitation delay specified by the INTVL= 
operand of the line group DCB macro, or by a POLLDLAY operator command. 
During the invitation delay, outgoing messages are sent to stations on the line in 
the order described in Message Priority and Queuing . (If the computer has no 
messages to send to stations on the line at this time, the invitation delay is ob- 
served nevertheless.) Outgoing messages are sent until the delay expires or the 
destination queues for stations on the line are empty. Upon expiration of the 
delay, outgoing message transmission ends after the current message is sent, 
regardless of whether any messages remain queued. As soon as outgoing message 
transmission ceases, polling and incoming message transmission resume, and the 
cycle is repeated. It is important to note that if no invitation delay is specified, 
outgoing message transmission does not occur. If an invitation delay is specified, 
it must be long enough to accommodate the expected density of outgoing message 
traffic; too short a delay causes outgoing messages to accumulate on the destina- 
tion queues for Unes or stations in a line group. 

If receiving and sending have equal priority, polling and incoming message traffic 
proceed without interruption until the end of the invitation Ust is reached. Then 
any outgoing messages are sent to stations on the Une in the order described in the 
Message Priority and Queuing section. Once outgoing transmission begins, it 
continues until aU messages queued for stations on the line have been sent, 
regardless of whether the user has specified an invitation delay. When all mes- 
sages for stations on the line have been sent, polling and incoming message traffic 
resume. Note that, in contrast to the case where receiving has priority over 
sending, outgoing message transmission occurs whether or not an invitation delay 
is specified and regardless of the specified length of the delay. 

If sending has priority over receiving, any outgoing messages are sent to a station: 

1. Each time a negative response to pofling is received from a station; 

2. Each time an EOT is received from a station, indicating that a complete mes- 
sage has been received; 

3. Each time the end of the invitation Ust is reached. 

Outgoing messages are sent in the order described in the Message Priority and 
Queuing section. Once outgoing message transmission begins, it continues until 
all messages queued for stations on the line have been sent. Note that when 
sending has priority over receiving, outgoing transmission can occur after each 
station is polled, rather than only after a complete polling pass. 

Auto Poll: For lines poUed under the control of the Auto Poll hardware feature, 
the scheme given above is sUghtly modified. 
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If receiving has priority over sending, messages are sent to stations on the line 
during the invitation delay. However, if no messages have been queued for 
stations on the line by the time the end of the invitation list is reached, no invita- 
tion delay is observed. 

If receiving and sending have equal priority, there is no difference between 
autopoUed and other polled lines. 

If sending has priority over receiving, outgoing messages are sent over autopoUed 
lines: 

1. Each time an EOT is received from a station, indicating that a complete mes- 
sage has been received; 

2. Each time the end of the invitation list is reached. 

Transmission Priority for Nonswitched Polled Stations Using TCAM^s Buffering 
Feature 

The IBM 2740 Model 2 contains a hardware buffer (and a message to the 2740 
Model 2 must fit within this buffer); the IBM 2770 on a multipoint line contains 
two hardware buffers. Messages to these stations fill the buffers at line speed. A 
message is read from the buffer to the terminal output device at the speed of the 
output device. This improves line utilization, since the Une is occupied with 
individual stations for short periods of time. If a buffered station is addressed 
before the buffer has emptied, a negative response is returned and the station 
must be selected again later. A message to be entered from a buffered station is 
first entered into the buffer from the input component (at the speed of the input 
device). When the buffer is filled or the message is entered, the message is trans- 
mitted to the CPU at line speed the next time the station is polled. 

TCAM sends to an IBM 2740 Model 2 a message at a time and to an IBM 2770 
until its buffer space is filled. The 2740 Model 2 accepts messages; thus, a block 
of data to the 2740 Model 2 must be equivalent to a whole message. To prevent 
TCAM from trying to send a message to a 2740 Model 2 while the hardware 
buffer is still emptying the previous message and thus wasting time on the line, 
TCAM allows the user to specify (in the BFDELAY= operand of the 
TERMINAL macro) the number of seconds to delay before sending each message 
after the first to a 2740 Model 2. The time specified should be the average time 
needed to empty the hardware buffer (the BFDELAY= operand must be speci- 
fied for the IBM 2770 also; see BSC device-dependent considerations in the 
SQCiiontiil&d Sending Operations in Appendix G). While this interval is in 
effect, TCAM can be sending messages to other stations on the line, thereby 
utiUzing the Une more efficiently. 

Thus, when BFDELAY= is specified for the 2740 Model 2 on a multipoint line, 
messages are sent to stations on the line on a message-by-message basis: the first 
message is sent; if there are messages queued for other stations on the line, they 
are sent; subsequent messages are sent as stations become available. For the 2740 
Model 2 to become eligible to accept another message, the time interval specified 
by the BFDELAY= operand of its TERMINAL macro must have elapsed. For 
information on how to determine the correct interval and restrictions on coding 
BFDELAY=, see the description of this operand in the TERMINAL macro. 

When a STOPLINE operator command, a QTAM STOPLN macro, a SYSCLOSE 
operator command, or an MCPCLOSE macro specifying a quick closedown is 
executed, transmission on a line to stations using TCAM's buffered-terminal 
support is not stopped until all messages being sent to stations on the line at the 
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time the command or macro is executed have been completely sent and all inter- 
vals specified by the BFDELAY= operand of the TERMINAL macros for 
stations on the line have been observed. 

For TCAM's buffering feature to work properly for the IBM 2740 Model 2, 
queuing by terminal and either equal or send priority must be specified in the 
TERMINAL and Une group DCB macros. 

Transmission Priority for Nonswitched Contention Stations 

The following can be nonswitched contention stations: the IBM 2740 Basic, the 
IBM 2780, the IBM 2770, World Trade (WTTA) terminals, and the IBM 
System/360, System/360 Model 20, and 1 130 Computing System. For non- 
switched contention stations, either equal or send priority may be specified. The 
way in which equal priority works is device-dependent, and is explained in 
Appendix G. 

Send priority is similar for all these types of stations. If send priority is specified, 
messages may be entered at the station whenever the line is idle. Whenever a 
message is queued for sending, TCAM checks to see whether a message is being 
entered by the station; if so, the computer waits until an EOT control character is 
received and then sends all messages queued for the station. If no message is 
being entered, the computer sends all queued messages immediately after check- 
ing. After sending all messages, the computer is ready to receive messages from 
the station. The invitation Ust for the Une may consist of a dummy entry (see the 
description of the INVLIST macro). 

For equal priority for the devices listed above, see Appendix G: Device- 
Dependent Considerations. f\ 

i 

When a BSC device is in contention with the CPU, TCAM defers to the BSC 
device for control of the line. However, when a start-stop device has a message to 
enter, and it is in contention with the CPU, the start-stop device loses that mes- 
sage (a Message Handler that includes the SEQUENCE macro can indicate when 
a message is lost to the system). 

Transmission Priority for Switched Stations 

For switched stations on a start-stop line, CPRI=S must be specified in the line 
group DCB macro. For BSC switched stations, CPRI=S or E may be specified. 

The relative order in which messages are sent to and received from a station on a 
switched line depends upon whether or not the station is a BSC station. 

When a non-BSC station calls the computer, once the connection is established, 

the station begins to enter any messages it may have ready for the computer. 

Before it can accept messages, the station caUing in must identify itself to the 

computer by an origin field, verified by an ORIGIN macro, in a message header. 

If the station does not identify itself, upon receiving a negative response to 

invitation, the computer sends the station any messages queued for the line entry 

for this Une. If no messages are queued for the line entry, or if there is no Une 

entry, the computer breaks the Une connection upon receiving a negative response 

to invitation, thereby making the line available for other caUs. Once the station 

identifies itself, it is eUgible to accept messages. If any messages were queued for 

the station at the time it identified itself, the station accepts these messages as j 

soon as possible; no further messages may be entered at the station until the i 

queued messages are sent. Messages are sent by the computer according to the 
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priority scheme outlined in the section Message Priority and Queuing . If the 
destination queue for the station was empty at the time the station identified itself, 
or once the queue becomes empty during this call, subsequent messages are sent 
to the station as soon as possible after they are placed on the destination queue. 
That is, whenever a message is completely enqueued on the previously empty 
destination queue during this call, TCAM checks to see whether a message is 
being entered by the station; if so, the computer waits until the message has been 
completely received, and then sends all messages queued for the station. After 
sending all messages, the computer invites the station to enter messages. When 
the last incoming message is received and no further messages appear on the 
destination queue for the station, the computer breaks the line connection, making 
the Une available for new calls. 

When the computer calls a non-BSC station, the computer sends all messages 
queued for the station before the station enters any messages (except that when 
the time specified in either the CLOCK= or the CINTVL= operand of the 
TERMINAL macro expires, TCAM invites the station to enter messages before it 
sends messages queued for the station). Messages are sent by the computer 
according to the priority scheme described in the section Message Priority and 
Queuing Once all queued messages have been sent, or if the qiieue was empty, the 
station begins entering any messages it may have ready. If a message is enqueued 
for the station after the station begins entering messages, TCAM sends the 
message as soon as the message currently being received from the station has 
finished, as described above. When the station indicates that it has no more 
messages to enter, and no further messages appear on the destination queue, 
TCAM breaks the Une connection, rendering the line available for new calls. 

See Appendix G. Device-Dependent Considerations for the transmission priority 
/ for: 

• 2740 Communications Terminal on a switched line; 

• Switched BSC stations; 

• Switched TWX stations. 

CaUs Between the Computer and a Switched Station 

On a line group basis, the order in which messages on a switched line are sent and 
received depends upon whether the computer dials a station or a station dials the 
computer, and upon when calls are made. 

In a TCAM system, a station may call the CPU on a line in its own line group that 
has a relative line number equal to or greater than the line to which the calUng 
station is assigned. When a station dials the computer, the response may be either 
manual, or automatic if it is equipped with the Auto Answer feature. 

If these requirements are satisfied, and if the line is not currently connected to 
another station, a connection is estabUshed each time the station dials the number 
associated with the line. If the Une is connected to another station when a station 
dials its number, the diaUng station receives a busy signal and must try again later. 
Once contact is successfully established between station and computer, message 
transmission occurs according to the scheme described in the section 
Transmission Priority for Switched Stations . 

If the computer is equipped with the Auto CaU feature, it may dial switched 
stations. For the computer to dial a switched station the station's telephone 
number must be entered in the DIALNO= operand of its TERMINAL macro 
(and the computer must be equipped with the Auto CaU feature). If CLOCK= is 
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coded for the TERMINAL macro, the computer dials the station only at the time 
specified by CLOCK=, and this is the only time at which the station may receive 
messages from the computer. If CLOCK= is specified, the station is invited to ( 

enter messages before TCAM sends messages queued for the station. 

If CLOCK= is not coded, an attempt is made to call the station whenever a 
message is completely received and enqueued in the previously empty destination 
queue for that station. (A destination queue is considered to be *'empty" when it 
contains no completely received, but as yet unsent, messages.) 

If the CINTVL= operand of the TERMINAL macro provides an interval, and the 
station does not call in and is not called during this time, TCAM calls the station 
at the end of the interval. (When the station calls in or is called during the speci- 
fied interval, the interval begins again.) When the time specified by CINTVL= 
expires, the station is invited to enter messages before TCAM sends those mes- 
sages queued for the station. If the specified interval has not expired, TCAM 
sends all messages queued for the station before the station is invited to enter its 
messages. 

When the first message arrives at the previously empty destination queue for a 

station (if CLOCK= is not coded), or the time specified by CLOCK= or 

CINTVL= is reached, the computer attempts to dial the station over the line 

specified by the RLN= operand of the TERMINAL macro for the station. If this 

line is currently being used by another station, the computer attempts to place the 

call over the line whose relative line number is one greater than that specified for 

this station. If this line is also being used by another station, the computer checks 

the Une whose relative line number is one higher than that for the Une just 

checked; this procedure is repeated until an available line is found, or until the line | 

having the highest relative line number in this line group is checked and found to i 

be in use. If the line with the highest relative Une number in the group is in use, 

the call is delayed until a line becomes available, at which time it is sent. If more 

than one waiting call is eUgible to be made over a line that has just become 

available, TCAM decides which call to make according to a priority scheme 

described below. Once the connection between computer and station is estab- 

Ushed, transmission occurs in accordance with the scheme described in the section 

Transmission Priority for Switched Stations. 

TCAM's caUing scheme is designed to take advantage of AT & T's Wide Area 
Telephone Service (WATS). If WATS is used, care should be taken to arrange the 
lines in a switched line group to take full advantage of the TCAM calling scheme. 
Lines should be arranged according to increasing area of WATS coverage, with 
the line covering the smallest area being assigned relative line #1, and the line 
covering the largest area being assigned the highest relative line number in the 
group. (The way in which lines in a line group are assigned relative line numbers 
is described in DD Statements for a Line Group in the chapter Defining the 
MCP Data Sets .) It is most economical for stations to be assigned to lines whose 
WATS coverage extend to their area and no farther; in no event should stations be 
assigned to a line whose coverage does not extend to their location. 

When a call cannot be made because all available lines in the Une group are busy, 

TCAM queues the request and defers the call until a suitable Une is available. If a 

line becomes available, and if there is more than one call that could be made over 

the line according to the rules described above, TCAM determines which station ^ 

wiU be caUed first by applying the following principles: 1 
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1. A station whose destination queue contains one or more messages having 
nonzero message priorities is called before a station whose destination queue 
contains only messages to which no message priority was assigned (that is, 
messages having zero priority). A station whose destination queue contains no 
complete messages is treated like a station whose queue contains only zero- 
priority messages {see 3 below). 

2. A station having a high-priority message on its destination queue is called 
before a station having low-priority messages on its destination queue. If the 
highest-priority messages on the queues for two eUgible stations are equal in 
priority (and if this priority is not zero), the time at which the last segments of 
the high-priority messages were enqueued determines which station is called; 
the station whose destination queue received the last segment of its highest- 
priority message first is called first. 

3. Among stations having only zero-priority messages on their destination queues, 
TCAM calls the station whose relative Une number is equal to, or closest to but 
lower than, the relative Une number of the available line. Among stations 
having only zero-priority messages on their destination queues and having the 
same relative Une number, TCAM caUs the eligible station whose queue was 
first to receive a complete message. 

4. Among stations whose queues contain no complete messages, TCAM calls the 
eUgible station for which the caU has been deferred the longest (this principle is 
applicable only for stations whose TERMINAL macro specifies CLOCK= or 
CINTVL=). 

Note that a strict WATS priority scheme for deferred caUs is observed only among 
stations whose destination queues contain only messages having zero priority. If 
relative line #6 becomes avaUable and caUs have been deferred for a station 
assigned to relative line #1 and for a station assigned to relative line #6, and if the 
queue for the station assigned to relative line #1 contains the highest-priority 
message, this station wiU be called before the other, even though it would be more 
economical from a WATS standpoint to caU the station assigned to relative line 
#6. (See Principle #2 above.) If the queues for both stations contain only zero- 
priority messages, a WATS priority scheme wiU be applied, and the station 
assigned to relative line #6 wiU be called first. (See Principle #3 above.) 

If the computer dials a station and gets a busy signal, it is treated as an error 
condition. The station's number will be dialed twice more; if no connection is 
established in three attempts, TCAM sets the selection error bit in the message 
error record, and the message is lost unless a REDIRECT or HOLD macro is 
executed for it in the outmessage subgroup. (The text error bit in the message 
error record may also be turned on — see the description of this bit in Appendix 
B.) 

Once the connection between the computer and a switched station is established, 
transmission occurs according to the scheme described in the section 
Transmission Priority for Switched Stations . 



Message flow is vitally affected by the system interval , a period of time specified 
by the INTVAL= operand of the INTRO macro. The INTERVAL operator 
command teUs TCAM to begin the system interval. When this message is re- 
ceived, each leased line to polled stations is "frozen" that is, receiving and sending 
of messages cease on it) at the start of its current polling pass. When all leased 
lines are inactive, the system interval commences. Lines to switched stations and 
local lines are left active; stations on such lines may stiU enter and accept mes- 
sages. A SYSINTVL operator command may be entered to change the duration 
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of the system interval. If this message is entered while a system interval is in 
effect, it does not change the duration of the current interval, but changes subse- 
quent intervals. 

The system interval is used to minimize unproductive polling, to minimize CPU 
meter time, and to synchronize polling on the polled lines in the system. In 
general, if there is no traffic on any Une in the TCAM system, the OS supervisor is 
given control to dispatch the next concurrent job. 



< 
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Structure of a Buffer 



Defining Buffers 



Messages entering a TCAM network are read into buffers, which are user-defined 
areas of main storage used for handUng, queuing, and transferring message 
segments between ail Hnes and queuing media, and between queuing media and 
appUcation-program work areas. (A message segment is that portion of a message 
contained in one buffer.) A buffer has two parts, one containing control informa- 
tion (the buffer prefix ) and the other containing all or part of the message. 
Buffers must be at least 35 bytes, and may be no larger than 65535 bytes. 



To provide the best dynamic buffering capability and use of main storage, the 
TCAM network has one buffer unit pool containing buffer units of one size. 
Buffer units are the basic building blocks from which buffers are constructed. 

The size of a unit is specified by the KEYLEN= operand of the INTRO macro of 
an MCP, and the number of units in the pool is equal to the sum of the numbers 
specified by the LNUNITS= and MSUNITS= operands of INTRO. For internal 
management purposes, 12 bytes are added by TCAM to the user-specified unit 
size. Thus, if a user specifies a unit size of 60 bytes (KEYLEN=60), the size of 
the unit becomes 72. The user should not concern himself with the extra 12 bytes 
when defining buffers. 

If .the sum of the number of bytes specified by the KEYLEN= operand plus 12 
bytes is not evenly divisible by eight, TCAM adds enough bytes to each unit to 
make its tqtal length divisible by eight. This is done so that units that are contigu- 
ous in main storage always start on a doubleword boundary. 

The size of a buffer for a line group is specified by the BUFSIZE= operand of the 
DCB macro defining the line group data set for that group. Each line group may 
use buffers that differ in size from those assigned to other line groups. 

By coding the BUFSIZE= operand of the TERMINAL macro, the user may 
override the buffer size specified in the line group DCB macro on a station-by- 
station basis, for outgoing messages only. 

By linking an appropriate number of units, TCAM constructs buffers containing a 
number of bytes at least as great as that specified by the BUFSIZE= operand of 
the DCB macro for a given line group. (The 12 bytes added to each unit by 
TCAM should not be considered in defining BUFSIZE=; the user should consid- 
er only the number of bytes he specified in the KEYLEN= operand of the INTRO 
macro.) For example, if the user specified KEYLEN=60 in the INTRO macro and 
BUFSIZE= 120 in a line group DCB, TCAM links together two units in building 
buffers for that line group. If, however, KEYLEN=60 and BUFSIZE= 100 is 
coded, TCAM will still link two units, but the last 20 bytes of the second unit 
cannot be used, and main-storage space is wasted. If KEYLEN=60 and 
BUFSIZE=40 is specified, the last 20 bytes of the first (and only) unit assigned 
are wasted. 

There are two types of logical buffers, header buffers and text buffers. A header 
buffer is a buffer that contains all or any part of a message header. A text buffer 
contains message text only. 



Defining Buffers 63 



A buffer prefix is a control area contained within each physical buffer of the 
system. The user must allow room for the buffer prefix in defining buffers. 
TCAM fills in the buffer prefix area with buffer control information. 

If only one buffer is used to contain a message, the buffer prefix occupies the first 
30 bytes of the buffer. If more than one buffer is used to contain a message, a 
30-byte buffer prefix occupies the beginning of the first buffer, and a 23-byte 
buffer prefix occupies the beginning of each subsequent buffer assigned to the 
message. 

Thus, there are two kinds of control areas associated with buffers. The 12-byte 
control area associated with each buffer unit is assigned automatically by TCAM 
and need be of no concern to the user when defining buffers. The 30-byte 
(header) or 23-byte (text) buffer prefix assigned to each buffer is of concern to 
the user, who must allow for this area in defining the size of his units. Each unit 
must be large enough to contain the larger prefix plus five bytes (35 bytes) and 
may be no larger than 255 bytes. Obviously, the second and subsequent buffers 
will contain more bytes of actual message than will the first buffer, since their 
prefixes are seven bytes shorter than that of the first buffer. 

Figure 2 shows how two buffers assigned to a line group would look if the user 
specified KEYLEN=60 and BUFSIZE=120. 
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Figure 2. Two Buffers Assigned to a Line Group; KEYLEN=60 and BUFSIZE=120 
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The Buffer Unit Pool 



Notice that each buffer is composed of two units linked together, and that the two 
buffers are also linked together. Each unit is 72 bytes long (the 60 bytes specified 
by KEYLEN= plus a 12-byte unit control area added by TCAM). In defining 
BUFSIZE for the line group, only the 60 bytes specified by the user were consid- 
ered. 

Remember that 

• a buffer is composed of one or more buffer units; 

• each buffer unit must be at least 35 bytes (not counting the 12-byte control 
area added by TCAM) and may be no larger than 255 bytes (not counting the 
unit control area); 

• each buffer must be at least 35 bytes (minimal size of one unit) and may be no 
larger than 65535 bytes. 



One buffer unit pool is defined for the Message Control Program. This single 
pool contains a number of buffer units equal to the sum of the numbers specified 
by the LNUNITS= and MSUNITS= operands of the INTRO macro. The total 
number of units in the unit pool must not exceed 65535. 

When message traffic is in progress, a unit in the unit pool may be in any one of 
three states: 

1 . If a main-storage message-queues data set is specified, some units are 
assigned to main-storage message queues; 

2. Some units are linked to form buffers assigned to line or application pro- 
grams to handle data transfer; 

3. Some units are assigned to an available-unit queue , where they remain until 
linked to form a buffer or until assigned to a message queue. 

Figures 3 and 4 show allocation of the units in a unit pool. Figure 3 illustrates 
how units are allocated when the user specifies main-storage message queuing 
with or without backup on reusable or nonreusable disk (see Defining the MCP 
Data Sets for a discussion of main-storage message queuing). 

The first block in Figure 3 depicts the unit pool just after storage has been allocat- 
ed for it, when main-storage queuing is specified. The pool consists of a number 
of units equal to the sum of the LNUNITS= and MSUNITS= operands of 
INTRO. Each unit has a length equal to the number of bytes specified by the 
KEYLEN= operand of INTRO, plus 12 bytes. All units are assigned to the 
available-unit queue. 

The second block in Figure 3 shows how the pool looks just before selection and 
invitation begin. A certain number of units have been linked to form buffers, 
which are assigned to line groups and application programs to handle initial send 
and receive operations (the number of buffers assigned is specified for Une groups 
by the BUFIN= and BUFOUT= keyword operands of the line group DCB macro, 
and for application programs by the BUFIN= and BUFOUT= operands of the 
PCB macro). All other units are still in the available-unit queue. 

The third block in Figure 3 illustrates the situation when normal message traffic is 
in progress. Some units are in line and application-program buffers; others are in 
main-storage message queues; the remainder are in the available buffer queue. 
The arrows represent the normal limits in size of the fraction of the unit pool that 
can be assigned to line and application-program buffers or to main-storage 
message queues after selection or invitation has begun. The number of units 
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assigned to main-storage message queues may never exceed the number specified 
by the MSUNITS= operand of INTRO. The number of units assigned to line and 
application-program buffers will not ordinarily exceed the number specified by the 
LNUNITS= operand of INTRO. However, under exceptional conditions (for 
example, when main-storage queuing with backup on disk is specified, and there is 
a peak period of line activity with low main-storage queue activity and high disk 
activity), the number of units assigned to line and application-program buffers 
may exceed the number specified by LNUNITS=, if the number of units required 
is available in the available-unit queue. 

Figure 4 illustrates how units are allocated when the user has specified disk 
queuing only for his message queues data set. 

The first block in Figure 4 depicts the unit pool just after storage has been allo- 
cated for it. The pool consists of a number of units equal to that specified by the 
LNUNITS= operand of INTRO. All units are assigned to the available-unit 
queue. 

The second block in Figure 4 shows how the pool looks just before selection or 
invitation commences. A certain number of units have been linked to form 
buffers, which are assigned to line groups and application programs to handle 
sending and receiving operations. All other units are on the available-unit queue. 

The third block in Figure 4 illustrates the situation when normal message traffic is 
in progress. Each unit in the pool is either assigned to a line or application- 
program buffer or assigned to the available-unit queue. The arrows illustrate the 
limit in size of the fraction of the unit pool that may be assigned to line buffers 
after selection or invitation has begun. All units on the available-unit queue may 
be assigned to line buffers. 

Buffers are not always available to be assigned to lines; for example, when TCAM 
does a Read operation for a data set residing on disk, a buffer is reserved to hold 
the record read from the disk. 

Buffers assigned to TCAM application programs differ from those assigned to the 
MCP in the way in which they are defined and in the manner in which they are 
allocated. For additional information on such buffers, see Defining Buffers for 
the Application Program in the chapter Writing TCAM -Compatible Application 
Programs , 
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Figure 3. Unit Allocation when Main-Storage Queuing (with or without Backup on Disk) is 
Specified 
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Figure 4. Unit Allocation when Disk-Only Queuing is Specified 
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Buffer Definition Checklist 

A checklist of the TCAM macro operands directly involved in MCP buffer 
definition follows. (A similar checklist for defining application-program buffers is 
contained in the chapter Writing TCAM-Compatible Application Programs .) The 
macros to which the operands belong are described in detail elsewhere in this 
publication. The user should first scan the checklist to give himself a general idea 
of what is involved in defining TCAM buffers, and then read the next section, 
which contains guidelines for coding many of these operands. Finally, the check- 
list may be used during actual buffer definition to assure that all applicable 
operands are coded. For information on maximum and minimum values and 
defaults, see the operand description for the. associated macro. 



Macro 
INTRO 



Operand 
KEYLEN=integer 



Line Group 
DCB 



LNUNITS=integer 



lBUFSIZE=integerJ 



Description of Function and Comments 

Specifies the length in bytes of a buffer unit. The unit as it exists in 
the unit pool is equal in length to the number of bytes specified by 
KEYLEN= plus a 12-byte control area added by TCAM. TCAM 
begins each unit on a doubleword boundary. In order to conserve 
main storage, the following formula can be used as a guideline in 
determining a value for KEYLEN= : 

KEYLEN=8x-12 

where x is any integer between 6 and 35, inclusive. A buffer unit 
must be large enough to accommodate the larger of: 

(a) a header prefix (30 bytes) plus the maximum number of reserve 
characters specified for the first buffer by the RESERVE = 
operand of any line group DCB macro or PCB macro plus 5 
bytes, or 

(b) a text prefix (23 bytes) plus the maximum number of reserve 
bytes specified for buffers other than the first by the 
RESERVE = operand of any line group DCB macro or PCB 
macro plus 5 bytes. 

Specifies the number of buffer units in the unit pool that may build 
line buffers and buffers to handle appUcation-program traffic. The 
sum of LNUNITS= plus MSUNITS= must not exceed 65535. 

Specifies the size of buffers to be used for ail lines in this line group. 
The size specified here may be overridden on a station basis for 
outgoing messages by means of the BUFSIZE= operand of the 
TERMINAL macro. The maximum number of units per buffer is 

255. 



[BUFIN=integer] 

[BUFOUT=integer] 

[BUFMAX=integer] 



Specifies the number of buffers assigned initially for receiving 
operations for each line in the line group. 

Specifies the number of buffers to be assigned initially for sending 
operations for each line in the line group. 

Specifies the maximum number of buffers allocated to a line at one 
time. If this operand is omitted, the larger of BUFIN= and 
BUFOUT= is assumed. 
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Macro 



Operand 



Description of Function and Comments 




Specifies whether and how program-controlled interruptions (PCI) 
are to be used for control of dynamic buffer allocation and 
deallocation. For the meaning of the operands, see the discussion 
of program-controlled interruptions in Dynamic and Static Buffer 
Allocation in this chapter. 



[RESERVE= 

(integer 1, 
[integer2])] 



TERMINAL [BUFSIZE=integer] 



LOGTYPE BUFSIZE=integer 



integer 1 specifies the number of bytes to be reserved in the first 
buffer of each incoming message for inserting data by the 
DATETIME and SEQUENCE macros, data by the DATETIME 
and SEQUENCE macros, integer! optionally specifies the number 
of bytes to be reserved in all buffers, except the first, for inserting 
characters by the DATETIME macro. See the descriptions of these 
macros, and the discussion of this operand in the description of the 
Hne group DCB macro. 

Overrides the buffer size specified by the BUFSIZE= operand of 
the line group DCB macro, but only for buffers containing outgoing 
messages destined for this station. 

Specifies the size of the buffers to handle messages destined for the 
logging medium when logging of messages is specified by a LOG 
macro. 



Design Considerations 



Management of data buffers for incoming and outgoing messages is an important 
factor in running a TCAM system at optimal efficiency. There are several factors 
that a system programmer must consider in weighing the trade-off of time and 
main storage. 

L The user must specify enough buffer units to assure no loss or undue delay of 
data. 

2. The user must select the size of the buffer units and buffers to accommodate 
his message. 

3. The user must decide whether to use the program-controlled interruption (PCI) 
feature for control of dynamic buffer allocation and deallocation. 

4. The user must determine the number of buffers to be assigned initially to each 
line in a line group for sending and receiving operations, and the maximum 
number of buffers to be assigned to each line. 

The following hsts may aid the system programmer in dealing with the first two of 
these factors; the other factors are discussed in turn below. 



( 



70 OS/MFT and OS/MVT TCAM Programmer's Guide 



Size of Buffers 



Relative Advantages of Larger vs. Smaller Buffers 
Parameter A dvantages 



larger buffers 

(more units per buffer) 



1. Fewer buffers required for a message; 
consequently overhead required by 
TCAM to manipulate buffers is de- 
creased. 

2. When dynamic allocation of buffers is 
used, the possibility of losing data be- 
cause of a delayed PCI is decreased. 

3. Number of PCIs required (if PCI is 
specified) is decreased. 

4. Better use is made of the disk access 

method employed by TCAM 
(multiple-arm support) because there 
is a larger number of contiguous re- 
cords than there would otherwise be. 

5. There are fewer queuing operations 
per quantity of data; this results in a 
saving of time. 



smaller buffers 
(fewer units per buffer) 



Units in smaller buffers tend to be 
returned to the available-unit queue 
more rapidly than units in larger buf- 
fers/ (since it takes less time to empty 
and fill a smaller than a larger buffer). 
Since units in smaller buffers are 
available for reuse sooner than equiv- 
alent units in larger buffers, a smaller 
unit pool is possible when smaller 
buffers are used. 
When smaller buffers are used, 
TCAM's work load is broken into 
smaller pieces; this results in a more 
equitable allocation of processing time 
among message segments in main 
storage. 
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Number of Units 



Relative Advantages of Having Many vs Few Units in the Pool 



Parameter 

more units in system 



fewer units in system 



Advantages 

1 . Likelihood of losing message data 
coming in over a line is decreased. 

2. Outgoing messages are less likely to 
be delayed as a result of waiting for a 
buffer. 

1 . Main storage is utilized more effi- 
ciently. Since the number of units in 
the free unit pool is not excessive, 
main storage is saved. 



Size of Units 



Relative Advantages of Larger and Smaller Units 



larger units 



1 . Disk space is used more efficiently, 
since there are fewer interrecord gaps. 

2. Proportion of area available for text 
to area containing management in- 
formation is relatively large. 

3. Since more data is transmitted per 
CCW on line and disk, channel activi- 
ty is relatively light; this results in a 
saving of channel fetch time and CPU 
time. 

4. Fewer channel program blocks 
(CPBs) are needed for transferring 
the same amount of data to and from 
disk; this results in a saving of storage 
space and time (since there is less 
queuing of CPBs). 



,1 



smaller units 



1. Duplicate headers (used for multiple 
routing of messages) take up little 
room. 

2. User can specify a large range of 
buffer sizes without wasting space in 
main storage and on disk. 

3. Allocation of buffers can be more 
dynamic with smaller units, since 
smaller units are passed around the 
TCAM system more rapidly than larg- 
er units. 



c 
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Dynamic and Static Buffer Allocation 

When the PCI= operand of the DCB for a Une group is coded to permit program- 
controlled interruptions, a PCI may occur during the fiUing of the first and each 
subsequent buffer assigned to a line group. When this interruption is received, 
control is given to a TCAM PCI routine. 

If PCI = A is coded, when the first interruption occurs, a number of buffers equal 
to the difference between the maximum number assigned to a line group (specified 
by the BUFMAX= operand of the DCB) and the number initially assigned to the 
line group (specified by the BUFIN= operand of the line group DCB for a 
receiving operation and by the BUFOUT= operand for a sending operation) is 
assigned as soon as possible to the line group. On subsequent PCIs, the buffer 
immediately preceding the one being filled or emptied is deallocated (for a sending 
operation, the buffer units are returned to the available-unit queue; for a receiving 
operation, the buffer is sent to the Message Handler for that line group) and a 
new buffer is requested to keep the number of buffers assigned to the line group 
equal to that specified by BUFMAX=. 

When PCI=R is coded, the previous buffer is deallocated when the second and 
subsequent PCIs occur, but no requests are made for additional buffers. If 
program-controlled interruptions are not permitted (PCI=N), or if only dealloca- 
tion is specified (PCI=R), then the number of buffers assigned initially must be 
sufficient to handle the entire transmission. 

If PCI=N is specified, no deallocation of buffers occurs until an BOB, ETB, or 
ETX control character is received; if the message contains no such characters, no 
deallocation occurs until the transmission is completed. 

If PCI=X is specified, after a buffer is filled (receive operations) or emptied (send 
operations) a PCI occurs while filUng or emptying the next buffer. The first 
buffer is not deallocated but a new one is allocated. Buffer deallocation occurs at 
the end of transmission, or when an EOB/ETB control character is sent, if 
STARTMH specifies EOB/ETB checking. 

Advantages: 

• When PCI= A is coded, fewer buffers need be assigned initially to a line since 
dynamic allocation brings the number of buffers assigned up to the value 
specified by BUFMAX= and maintains this number if possible. 

• When PCI=A is coded and a negative response to invitation occurs, only the 
number of buffers assigned initially, rather than the maximum number assigned 
to the line, have been fruitlessly allocated. 
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• When PCI= is specified as A or R, buffers are continuously being deallocated; 
the free-unit pool is therefore continuously being replenished and a smaller unit 
pool is required. 

• When PCI= specifies A or R, a message is moved one buffer at a time; there- 
fore, fewer CPBs are required. 

Disadvantages: 

• Dynamic allocation and deallocation of buffers takes processing time. 

• When reusable disk queues are used, records written to disk by the PCI inter- 
rupt are not serviced until the entire message is queued. If the length of time 
required to enter a message is excessive, or if reusability servicing is very 
frequent, records may be overlaid. If this occurs, TCAM will terminate abnor- 
mally with a system code of 045 and with a return code of 02 or 03 in register 
15. 

Note: In order for dynamic allocation to work properly for BSC lines, the 
BUFMAX= operand of the line group DCB macro must specify a value that 
is at least two greater than that specified by the larger of either the 
BUFIN= or the BUFOUT= operand of the line group DCB macro. 

For start-stop lines using dynamic allocation, a specification of BUFIN=2, 
BUFMAX=2 may cause inefficient dynamic allocation. 

Initial and Maximum Number of Buffers per Line 

The number of buffers that should be assigned initially to each line in the line 
group (by the BUFIN= and BUFOUT= operands of the line group DCB macro) 
depends upon the following factors: 

• terminal type; (| 

• terminal speed; 

• line speed; 

• whether dynamic allocation of buffers is specified. 

The number of buffers to be assigned initially varies directly with the speed of the 
line and the terminal; the faster the data is transmitted, the higher the initial 
assignment should be. 

The maximum number of buffers assigned to a line in the group (by the 
BUFMAX= operand of the line group DCB macro) also depends upon the Une 
and terminal speed. For a system using dynamic allocation of buffers, allowance 
should be made for the fact that program-controlled interruptions might not be 
accepted by the CPU in time for buffer replenishment to be effective for any 
particular buffer. For high-speed BSC lines, dynamic allocation may not be 
totally effective; that is, there may not be a one-to-one correspondence of re- 
placement buffers to replaced buffers. If this happens consistently, incoming data 
may be lost and bit 6 turned on in the message error record. The higher the Hne 
speed, the greater the disparity may become. When dynamic allocation is not used 
by the system, BUFMAX= is ignored. 

The buffers assigned to each line in a line group by the BUFIN= operand of the 
Une group DCB macro and the buffers assigned to each line by the BUFOUT= 
operand of the line group DCB macro are never assigned to the same line at the 
same time. The buffers specified by BUFIN= are assigned to a Une just before a 
station is invited by TCAM to enter a message; the buffers specified by 
BUFOUT= are assigned immediately before a station on the line is selected to i 

receive a message. Hence, when the user is deciding how many units to define to 



74 OS/MFT and OS/MVT TCAM Programmer's Guide 



handle initial line operations, he need consider only the larger of the values 
specified by BUFOUT= and BUFIN= for each line in a hne group, and not the 
sum of the two values. 

Other Buffer Design Considerations 

• If the buffer size (as specified by the BUFSIZE= operand of the Hne group 
DCB, TERMINAL, LOGTYPE, or PCB macro, or the BUFL= operand of the 
input or output DCB) is not a multiple of the effective unit size (as specified by 
the KEYLEN= operand of the INTRO macro), buffer space is wasted. For 
example, if the INTRO macro specifies KEYLEN=36 and the DCB macro for 
a line group specifies BUFSIZE=100, 108 bytes (that is, 36 X 3) are assigned 
to the buffer, but only 100 bytes are available for prefix and message data. 
Thus, 8 bytes are wasted for each such buffer. 

• If disk queuing is used, try to ensure that the buffer size specified by the source 
of a message is equal to the buffer size specified by the destination. The source 
of a message may be either a station or an appHcation program. If it is a 
station, that station's line group DCB macro determines the buffer size of 
messages that it may enter; if it is an appHcation program, a PCB macro deter- 
mines buffer size. The destination for a message also may be either a station or 
an application program. Buffer size for an accepting station is determined 
either by that station's Hne group DCB macro or a TERMINAL macro (if the 
buffer size is specified on the TERMINAL macro, this value overrides the value 
specified on the Hne group DCB). A PCB macro determines buffer size for an 
appHcation program that is the destination for a message. When the buffer 
sizes specified for the origin and the destination of a message are different, data 
movement occurs because of the necessity of adding or deleting prefixes when 
the message is placed in the buffers for the destination. (The message is 
queued on disk with its old prefixes; when it is removed from a queue and 
placed in buffers of a different size, prefixes must be added or removed and 
message data must consequently be shifted.) Movement of data takes time. 
Figure 5 illustrates a situation in which 706 bytes of a 1076-byte message must 
be moved because of a difference in origin and destination buffer size. 

• TCAM does not consider a message that has been sent to an appHcation 
program to be ^'serviced" until the succeeding GET is completed; therefore, 
buffers are not released until the succeeding GET is completed and extra 
buffers must be aHocated to compensate for those not released yet. 

Buffering and queuing are closely related concepts; the discussions of main- 
storage and disk queuing in the chapter Defining Data Sets should be read in 
conjunction with the present chapter. 
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Figure 5. 706-Byte Data Movement Resulting from Size Disparity between Input and Output Buffers 
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Defining the MCP Data Sets 



The Message Control Program may refer to four types of data sets. Two are 
required for every MCP: 

• The Une group data set and 

• The message queues data set. 

The two optional data sets are: 

• The checkpoint data set, if the checkpoint facility is desired; 

• The log data set, if the logging function is desired. 

Log data sets are not TCAM data sets; they are discussed briefly below. Other 
data sets are needed if there are any application programs; these data sets are 
described in the chapter dealing with TCAM support for application programs. 

With one exception (a message queues data set in main storage with no disk 
backup), TCAM data sets are defined by DCB macro instructions. The total 
number of TCAM MCP data sets may not exceed 255. 



Line Group Data Sets 



A line group data set consists of the lines in a line group over which messages are 
transmitted to and from the central processing unit. The user must specify one 
line group DCB macro instruction for each line group in the system. 

Characteristics of a Line Group 

A line group may consist of from one to 255 lines. (The size of a Une group is also 
limited by the fact that the INVLIST= operand of the line group DCB macro can 
be no longer than 255 characters, including commas; thus, if each of 255 lines has 
an invitation list associated with it, the Unes cannot all be accommodated within 
the same Une group.) AU Unes in the group must have the following common 
characteristics: 

Either aU Unes in the group are switched or aU are nonswitched. 
Either all lines in the group use start-stop transmission or all use binary syn- 
chronous transmission. 

AU Unes are associated with stations having the same device characteristics. 
AU lines are preassigned the same number of buffers to handle the initial 
segments of incoming messages. 
All Unes use the same invitation delay. 
AU lines use the same Message Handler. 
No line in the group is a member of another group. 

AU lines in the group are associated with the same type of transmission control 
unit. 

Creating a Line Group Data Set 

A Une group data set is defined by a Une group DCB macro instruction, which 
creates a data control block for the line group. Parameters based on the keyword 
operands specified in the macro are included in the data control block. 

Operands of the line group DCB macro enable one to specify functions concerned 
with buffering (BUFOUT, BUFIN, BUFSIZE, BUFMAX, PCI), polling (INTVL, 
CPRI, INVLIST), and message translation (TRANS) on a line-group basis. These 
operands are described in detaU in the next section. Various aspects of polling 
and translation are discussed in the chapter Defining Terminal and Line 
Control Areas , whUe the chapter Defining Buffers includes a discussion of how 
to code the DCB operands concerned with buffering. 



Defining the MCP Data Sets 77 



^ 



< 



linedcb 



keyword operands 



Line Group DCB Macro 



The line group DCB macro 

• defines a line group data set; 

• must be issued for each line group in the TCAM system; 

• identifies the Message Handler for the lines in this line group; 

• identifies the invitation Usts assigned to the lines in this group; 

• specifies the invitation delay; 

• indicates transmission priority for stations on Unes in this group; 

• specifies the number of buffers assigned initially to Unes in this group for 
sending and receiving operations; 

• specifies when buffers servicing Unes in this group are to be allocated and 
deaUocated; 

• specifies the buffer size for buffers servicing lines in this group; 

• specifies the maximum number of buffers assigned to a line at one time; 

• specifies the number of bytes to be reserved for insertion of certain data into 
buffers; 

• specifies the translation tables to be used for incoming and outgoing messages. 

The line group DCB macro defines a data control block for a line group data set. 
Parameters based on the keyword operands specified in the macro are included in 
the data control block. One line group DCB macro must be issued for each Une 
group in the TCAM system. The macro generates no executable code. 

The Une group DCB macro has the following format: 



Name 


Operation 


Operands 


linedcb 


DCB 


keyword operands 



Function: Specifies the name for the macro instruction and also for the data 

control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Are the operands that can be specified. They are described below. 
Notes: The operands may be specified in any order and are separated by commas 
with no intervening blanks. When a parameter can be provided by an alternate 
source, a symbol appears in the Alternate Source description for the operand 
associated with that parameter. When there is not an alternate source (that is, the 
parameter must be specified by the operand), the alternate source descriptor 
states None . The symbols have the following meanings: 

Symbol Explanation 

DD The value of the operand can be provided at execution time by the 

data definition (DD) card for the data set. If a value is provided 
by a DD statement, the macro operand must be either omitted or 
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OE 



coded with a zero value (if the operand is omitted, a zero value is 
supplied by TC AM). 

The value of the operand can be provided by the problem program 
any time up to and including the data control block exit at open 
time. 



PP 



The value of the operand can be provided by the user's problem 
program any time before the data control block exit at open time. 



DSORG=TX 



MACRF=(G,P) 



If DD is specified, OE or PP may also be used. If OE is specified, PP may also be 
used. For information on providing parameters by DD, see the section DD 
Statements for a Line Group , For information on providing parameters by OE 
or PP, see Modifying the Data Control Block in the OS Data Management 
Services publication. 

The formats of macro illustrations, the symbols used in them, and rules for the 
interpretation of operand descriptions are all provided in Appendix A . 



Alternate Source: None. 

Function: Identifies the data set organization as that for a line group. 

Default: None. This operand is required. 

Format: DSORG=TX 



Alternate Source: None. 

Function: Specifies that access to the line group is gained with GET and PUT 

macro instructions. 

Default: None. This operand is required. 

Format: MACRF=(G,P) 



INTVL= ( integer) 
\0 / 



Alternate Source: PP, OE, DD. 

Function: Specifies the numer of seconds of intentional delay between passes 
through an invitation list). 
Default: INTVL=0 
Format: Unframed decimal integer. 
Maximum: 255 

Notes: After all the stations in an invitation list for a given Une have been invited 
to enter a message, a delay, equal to the number of seconds specified in this 
operand, occurs before invitation is restarted at the beginning of the Ust. Invita- 
tion delay is discussed in Transmission Priority in the chapter Defining Terminal 
and Line Control Areas. For switched lines, INT VL=0 should be specified. 

If tone generation is required for World Trade terminals, INTVL= 1 should be 
coded. 



< 
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CPRI= 




Alternate Source: PP, OE, DD. 

Function: Specifies the relative transmission priority assigned to the lines in this 

line group. 

Default: None. This operand is required. 

Format: R, E, or S. 

Notes: R specifies that CPU receiving has priority over CPU sending. E specifies 

that receiving and sending have equal priority. S specifies that sending has 

priority over receiving. See Transmission Priority in the chapter Defining 

Terminal and Line Control Areas for a discussion of the effect of transmission 

priority on sending messages. 



DDNAIVlE=ddname 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



EXLST=address 



Alternate Source: PP. 

Function : Specifies the address of the problem program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This list must be provided if data control block or user ABEND exits are 

required, and must start on a fuUword boundary. The format and contents of the 

list, and Unkage conventions to be followed when using it, are shown in the OS 

Data Management Services pubUcation. User ABEND exits are described in the 

last section of this chapter. The DCB exit is also described in Data Management 

Services . 



BUFIN= 



( integer) 



Alternate Source: PP, OE, DD. 

Function: Specifies the number of buffers assigned initially for receiving opera- 
tions for each line in the line group. 

Default: BUFIN= 1. This default is supplied at open time, rather than at assem- 
bly time. 

Format: Unframed nonzero decimal integer. 
Maximum: 15 

Notes: These buffers are assigned just before a station is permitted to enter a 
message. BUFIN=, BUFOUT=, and BUFMAX= must all be specified from the 
same source. For more information on initial assignments of buffers, see the 
chapter Defining Buffers . 



\ 
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BUFOUT=J integer | 

V- / 



Alternate Source: PP, OE, DD. 

Function: Specifies the number of buffers assigned initially for sending opera- 
tions on each line in the line group. 

Default: BUFOUT=2. This default is supplied at open time, rather than at 
assembly time. 

Format: An unf ramed decimal integer greater than 1 . 
Maximum: 15 

Notes: BUFIN=, BUFOUT=, and BUFMAX= must all be specified from the 
same source. 



BUFMAX=J integer I 



BUFSIZE=integer 



Alternate Source: PP, OE, DD. 

Function: Specifies the maximum number of buffers used for data transfer. 

Alternate Source: PP, OE, DD. 

Function: Specifies the maximum number of buffers used for data transfer for 

each Une in this line group. 

Default: BUFMAX=2. This default is supplied at open time, rather than at 

assembly time. 

Format: Unf ramed decimal integer greater than 1 . 

Maximum: 15 

Notes: Must be no less than the larger of the numbers specified by BUFIN= and 

BUFOUT=. BUFIN=, BUFOUT=, and BUFMAX= must all be specified from 

the same source. 



Alternate Sourve: PP, OE, DD. 

Function: Specifies the buffer size in bytes used for all lines in this Une group. 

Default: None. Specification optional. 

Format: Unf ramed decimal integer greater than 35. 

Maximum: 65535 

Notes: The size specified here may be overridden on a station basis for outgoing 

messages by the BUFSIZE= operand of the TERMINAL macro. If the buffer 

size is not an even multiple of the buffer unit size specified by the KEYLEN= 

operand of the INTRO macro, storage space is wasted. The maximum number of 

units per buffer is 255. 



,4 



INVLIST=(listname 



■•jii"iii' 



Alternate Source: None. 

Function: Specifies the names of the invitation lists for the lines in the line group. 

Default: None. This operand is required. 

Format: Each listname is the name specified for the INVLIST macro defining 

the Ust for that line. Listnames are specified according to the ascending relative 

Une numbers of the lines in the group. The maximum total length of the data 

coded for this operand is 255 bytes. A and B are coded as shown. 

Notes: For information on relative line numbers, see DD Statements for a 

Line Group in this chapter. 



( 
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There must be one invitation list name for each Une in the line group. If a line is 
used for output only, a dummy invitation list name with no entries is specified. 
Any number of output-only lines may refer to the same name. No list other than a 
dummy invitation Ust may be named by more than one line. For information on 
invitation lists, see the Invitation section in Defining Terminal and Line 
Control Areas. 

The two sets of A/B suboperands are meaningful only for lines attached to a 
channel through an IBM 2701 Transmission Control Unit, in which case: 

The first A specifies that communications are to be through the 2701 Data 
Adapter Unit's Dual Communication Interface A. 

The first B specifies that communications are to be through the 270 1's Dual 
Communication Interface B. This parameter is not coded if this feature is not 
present on the 2701. 

The second A specifies that transmission will be in Code A for the 2701 Data 
Adapter Unit Dual Code Feature. 

The second B specifies that transmission will be in Code B for the 2701 Dual 
Code Feature. This parameter is not coded if this feature is not present on the 
2701. 

A is the default value for both sets of suboperands. 

If either or both of the A/B suboperands are omitted, the commas that precede 
them must still be coded. For example, if the names of the invitation lists for the 
lines in this line group are LISTl, LIST2, and LIST3, and if the A/B suboperands 
are to be omitted from this operand, the operand might be coded as follows: 

,INVLIST=( LISTl 



Alternate source: None. 

Function: Specifies the name of the Message Handler for the line group repre- 
sented by this DCB macro. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols, and must be 
the same as the name specified in the name field of a STARTMH macro. 



Alternate Source: PP, OE, DD. 

Function: Specifies if and how a program-controlled interruption (PCI) is to be 
used for control of buffer allocation and deallocation. 
Default: (PCI=A, A). This default is supplied at open time, rather than at 
assembly time. 

Format: Framing parentheses required. N, R, X, and A coded as shown. 
Notes: The suboperands apply to receiving and sending operations, respectively. 
N specifies that no PCIs are taken during filling (on receive operations) or empty- 
ing (on send operations) of buffers. Once data in a buffer has undergone BOB 
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checking, the buffer is deallocated (except that the current buffer is not deallocat- 
ed if there is room in it for a portion of the next block). 

R specifies that after the first buffer is filled (on receive operations) or emptied 
(on send operations), a PCI occurs during the filling or emptying of each succeed- 
ing buffer. The finished buffer is deallocated, but no new buffer is allocated to 
take its place. 

X specifies that after a buffer is filled (on receive operations) or emptied (on send 
operations), a PCI occurs during the filling or emptying of the next buffer. The 
first buffer is not deallocated, but a new buffer is allocated. Buffer deallocation 
occurs at the end of transmission, or when an EOB/ETB control character is sent, 
if EOB/ETB checking is specified in the STARTMH macro. 

PCI=X (or N) must be used if the TCAM network defines logical messages, and 
if the SETEOM macro specifies PROCESS= YES, to ensure that logical messages 
are not deblocked until block checking is performed; otherwise, a logical message 
containing an error could be routed to its destination. Logical messages are 
discussed in Handling Logical Messages in the chapter Designing the Message 
Handler . The SETEOM macro is discussed in Functional Macro Instructions . 

A specifies that after the first buffer is filled (on receive operations) or emptied 
(on send operations), a PCI occurs during the filling or emptying of the next 
buffer. The first buffer is deallocated, and another buffer is allocated in place of 
it. The program-controlled interruption is more thoroughly described in the 
chapter Defining Buffers . 

RESERVE= ( UntegerlM,i integer! H j \| 

Alternate Source: PP, OE, DD. 

Function: integer 1 specifies the number of bytes reserved in the first unit of a 
buffer receiving the first incoming segment of each message entered on a Hne in 
this line group. The reserved bytes are for insertion of characters by the 
DATETIME and SEQUENCE macros, integer I may be specified as one less 
than the required number of reserved bytes if LC=OUT is specified on the 
STARTMH macro and the terminal in use has EOA Hne-control characters. 
(TCAM's use of LC=OUT results in the conversion of EOA Une-control charac- 
ters to reserve characters which, in effect, gives the user one more reserve charac- 
ter than is specified on the line group DCB macro.) integer! specifies the number 
of bytes reserved in the first unit of all buffers, except the first, for insertion of 
characters by the DATETIME macro. 
Default: RESERVE=(0,0) 
Format: Unframed decimal integers. 
Maximum: For each, 255. 

Notes: integer! is relevant only in a multiple-buffer header situation when 
DATETIME is to insert data in a portion of the header that is not in the first 
buffer (see the description of DATETIME for an example of executing 
DATETIME on a portion of the header not located in the first segment). 

Data may be inserted in either an incoming or an outgoing message header, but 
space must be reserved in the incoming header. On the outgoing side, reserved 
space is retained for the first buffer only; thus, a DATETIME or SEQUENCE 
macro, if specified in an outheader subgroup, must operate on the first segment of 



( 
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TRANS= table 



the message. No space need be reserved for data inserted by means of a 
MSGEDIT macro. 

The Scan Pointer section of the chapter Designing a Message Handler de- 
scribes how TCAM handles reserve bytes. 

Each integer must be at least three less than the value specified in the KEYLEN= 
operand of the INTRO macro, minus the header or text prefix size Each buffer 
containing header data should be large enough to accommodate the segment itself 
plus any data that may be inserted by DATETIME and SEQUENCE macros. If a 
buffer containing header data does not have a sufficient number of bytes reserved 
in it to accommodate data inserted by a DATETIME or SEQUENCE macro, the 
macro does not execute, and control is passed to the next instruction in the MH. 
Unused reserve bytes are removed from an outgoing message segment when it is 
sent to its destination. 



Alternate Source: PP, OE. 

Function: Specifies the translation table for this line group. 

Default: TRANS=EBCD. This default is supplied at open time rather than at 

assembly time. 

Format: Either the name of a user-defined table conforming to the rules for 

assembler language symbols, or one of the following four-byte symbols: 

1030 1030 transmission code 

1050 1050 transmission code 

105F Folded 1050 transmission code 

1060 1060 transmission code 

2260 2260 remote transmission code 

2265 2265 transmission code 

2740 2740 transmission code 

274F Folded 2740 transmission code 

BC41 2741 BCD code 

EB41 2741 EBCDIC code 

CR41 2741 correspondence code 

ITA2 World Trade terminals transmission code 

ZSC3 World Trade terminals transmission code 

TTYA 83B3, 1 15A transmission code 

TT YB 33/35 parity transmission code 

TTYC 33/35 non-parity transmission code 

6BIT 2780 6-bit transmission code 

ASCI 2780, 3270, 3670, 3735, 360 CPUs, Model 20 ASCII tranmission 

code 

EBCD 2770, 2790, 3270, 3670, 3780, 1 130, 2260 Local, 2780, 360 CPUs, 

Model 20 EBCDIC transmission code. 

Notes: Specification of a user-defined table is described in Message Translation 
in the chapter Designing the Message Handler 

Translation is from transmission code to EBCDIC for incoming messages and 
from EBCDIC to transmission code for outgoing messages. For incoming transla- 
tion to occur, a CODE macro must be executed in the incoming group handling 
the message. For outgoing translation to occur, CODE must be executed in the 
outgoing group handling the message. If this operand is omitted, no translation is 
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performed. TRANS = ASCI must be specified for US ASCII 3270 terminals 
whether or not data is to be translated. 

The table specified for translation can be changed for messages from a particular 
line or station by the CODE macro and by the use of path switches. 
TRANS=EBCD should be coded for lines to stations using EBCDIC line code, if 
any of the stations may enter operator commands (TCAM uses the CODE macro 
to check for operator commands). 

For more information on the symbols, and on translation in the TCAM system, 
see Message Translation and the description of the CODE macro in the chapter 
Designing a Message Handler. 



Alternate Source: None. 

Function: Specifies the name of the special characters table (SCT) used for this 

Hne group. 

Default: The table specified for the TRANS= operand is assumed for the SCT= 

operand if this operand is omitted. 

Format: One of the four-byte codes permissible for the TRANS= operand. 

Notes: If a user-specified table is coded for the TRANS= operand, the SCT= 

operand must be coded. The SCT is an internal TCAM table containing certain 

device-specific, line-control characters needed by TCAM whether or not Une- 

control characters are left in incoming messages. TCAM makes no provision for 

the user to specify his own special characters table. The contents and layout of 

the SCT are described in the TCAM PLM . 



A 



DD Statements for a Line Group i 

At least one DD statement must be issued for each line group data set. Either of 
two schemes may be followed in issuing DD statements for Une groups. 

1 . If at system generation time a UNITNAME macro is issued to specify the lines 
in a Une group and to assign to them a single name, then a single DD statement 
may be issued for this line group at MCP execution time. This DD statement 
would have the format 

//ddname DD UNIT=( name,n ) 

where ddname is the name specified by the DDNAME = operand of the DCB 
macro for the line group, name is the name assigned to this group of lines by 
the NAME= operand of the UNITNAME macro, and n is the number of lines 
to be allocated from among the lines whose hardware addresses are coded in 
the UNIT= operand of UNITNAME. 

Example: 

At system generation time, the following UNITNAME macro was issued to 
define a group of lines: 

UNITNAME UNIT=( 021 ,022,024,025 ) 
NAME-GROUPONE 

(The four numbers in the UNIT= operand are the hardware addresses of four 
lines, and are assigned to the lines by lODEVICE macros at system generation 
time.) At execution time for the Message Control Program, the following DD 
statement might be issued for this line group: 
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//ddname DD UNIT=( GROUPONE, 4 ) 

In this case, the Une group data set would consist of the four Hnes defined by 
the UNITNAME macro. Relative line numbers are assigned to the lines in the 
same order as they appear in the UNIT= operand of the UNITNAME macro. 
If the UNIT parameter of the DD statement were coded 

UNIT=(GROUPONE,2), the line group data set would consist of only the first 
two lines specified in the UNIT= operand of the UNITNAME macro. 
2. A DD statement may be issued for each Une in a line group; these DD state- 
ments are concatenated as follows (assume that the Une group consists of three 
lines): 

//ddname DD UNIT=address 
// DD UNIT=address 
// DD UNIT=address 

where ddname is the name specified by the DDNAME= operand of the DCB 
macro for the Une group, and address is the hardware address of the Une, as 
assigned at system generation time by an lODEVICE macro. Note that DD 
statements for aU lines in a line group are Usted under a single ddname . When 
this scheme is used, the order in which the DD statements for a Une group are 
arranged determines the relative Une numbers specified in TERMINAL macros; 
that is, the first Une specified is relative line number one, the second Une 
specified is relative line number two, etc. (see the discussion of the TERMI- 
NAL macro in the chapter Defining Terminal and Line Control Areas . 

Note: The type of stations on lines in the line group for which the DD 
statement is issued must be the same as the type specified by the lODEVICE 
macro that defines the line at system generation time. Be sure that the line 
you specify in the UNIT= parameter of your DD statement can handle the 
stations assigned to that line by TERMINAL macros. Otherwise, the data 
set will not open. 

Certain of the line group DCB macro operands may be omitted from the DCB 
macro and be specified at MCP program execution time by coding them as 
subparameters in the DCB parameter of the first DD statement for a Une group. 
The way in which the DCB parameter would be coded to specify any one of these 
DCB macro operands is: 

DCB=( BUFIN=integer , BUFOUT=integer , BUFMAX=integer ) 
DCB=( INTVL=integer ) 

DCB=(CPRI=^E> ) 

DCB=( RESERVE=( integer [ , integer] ) ) 
DCB=(PCI = (( N I , ^ N, 

DCB=( BUFSIZE=integer ) 

These subparameters are described in the discussion of the Une group DCB macro. 
More than one DCB operand may be specified in this manner. Note that the 
BUFIN=, BUFOUT=, and BUFMAX= values must be specified from the same 
source. 

If the above DCB operands are stiU zero after OPEN, the following defaults are 
used: 
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//ddname 


DD 


// 


DD 


// 


DD 



BUFIN=1 

BUF0UT=2 

BUFMAX=2 ( 

CPRI=S 

RESERVE=0 

PCI=(N,N) 

BUFSIZE=value of KEYLEN= on INTRO 

Example: 

The following DD statements define a line group consisting of three lines. The 
PCI= operand was not specified in the line group DCB macro, but is being 
specified at program execution time on the DD statement. 

UNIT=024,DCB=( PCI=(R,R) ) 

UNIT=022 

UNIT=025 

In this example, the line whose address is 024 is assigned relative line number 1, 
the line whose address is 022 is assigned relative Une number 2, and the Une whose 
address is 025 is assigned relative line number 3. 

Message Queues Data Sets 

In a TCAM system, messages entered by remote stations are queued by destina- 
tion. A destination may be a station on a Une or an appHcation program. Because 
each incoming message is placed on a queue for its destination rather than being 
sent to the destination immediately, overlap of line usage in I/O operations is 
possible. Messages having a common destination may be received simultaneously 
from more than one source; the destination itself may also be entering or accept- 
ing a message. 4 

Destination queues for each destination (Une, terminal, or appUcation program) 
and a queue for each logging medium used (for message logging) are located in 
one or more message queues data sets, which may reside either in main storage or 
on a direct-access storage device. Messages may be queued 

• on reusable disk; 

• on nonreusable disk; 

• in main storage only; 

• in main storage with backup on reusable disk; 

• in main storage with backup on nonreusable disk. 

Although there are five queuing techniques, no more than three message queues 
data sets ever need to be defined; one on reusable disk, one on nonreusable disk, 
and one in main storage. 

In the foUowing discussion we shaU first explain each of the five message queuing 
techniques, giving their relative advantages and disadvantages, and then describe 
how each may be implemented. 

Messages may be queued by destination Une or by destination terminal; this topic 
is discussed in the Message Priority and Queuing section of the Defining 
Terminal and Line Control Areas chapter. 



Disk Queuing 
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TCAM supports secondary-storage message queuing on the IBM 23 11 Disk 

Storage Drive, the IBM 2314 Direct Access Storage Facility, and the IBM 3330 i 

Disk Drive ^ 



The objective of TCAM's secondary-storage queuing scheme is to optimize 
channel and disk performance. Rotational delay time is minimized by using 
sequential disk records wherever possible. The user may specify more than one 
DASD volume for a data set; if he does, TCAM assigns relative record addresses 
across volumes, so that the next relative record address after that of the last 
record on a track is on another volume. Figure 6 illustrates this relative-record 
addressing scheme, which facilitates efficient multiple-arm support. TCAM's 
multiple-arm support (described below) permits overlap of seek time on multiple 
volumes and overlap of channel operations on multiple channels. Seek time is 
further optimized by minimizing disk arm movement. 

Advantages and Disadvantages of Disk Queuing 

Locating destination queues in a message queues data set residing on a disk rather 
than in a data set residing in main storage with no disk backup results in certain 
advantages: 

1. Locating queues on disk rather than in main storage results in more main 
storage being available to the user. 

2. With disk queuing, messages being sent to a station that temporarily inoperative 
may be intercepted by a HOLD macro issued in the Message Handler, and sent 
out at a later time. The interception facility is not available for destinations 
whose queues are located in a main-storage data set having no disk backup. 

3. By issuing a POINT macro in conjunction with a GET or READ macro in an 
application program, the user may retrieve from its destination queue the 
original copy of a message that has already been successfully transmitted to a 
destination station or sent to an application program. This retrieval capabihty 
(discussed in the Message Retrieval section of the chapter Writing TCAM- 
Compatible Application Programs) mighi be used to permit a message that was 
successfully sent to a terminal but lost at the terminal (due, perhaps, to a tape 
breakage) to be retransmitted. Messages cannot be retrieved from main- 
storage queues. 

4. When disk queuing is used, it is possible to take advantage of the TCAM 
checkpoint/restart facility, which is described in the chapter Using TCAM 
Service Facilities . Main-storage queues cannot be checkpointed; unless disk 
backup is provided, the data in such queues is lost when the TCAM system 
closesdown or fails. 

Locating message queues in a data set on disk rather than in a main-storage data 
set also has certain disadvantages: 

L Disk queuing is slower than main-storage queuing; that is, a message that is 
queued on disk takes longer to reach its destination than a message that is 
queued in main storage, all other things being equal. 

2. Disk queuing ties up disk space and disk channels that otherwise could be used 
by other jobs (for example, by a batch-processing job) in a computing system 
not dedicated to TCAM. 

Main-storage queuing with disk backup (discussed below) preserves most of the 
advantages of disk queuing while achieving a faster response time than disk 
queuing alone. To obtain main-storage queuing with disk backup, the user must 
define at least two message queues data sets — one residing in main storage, the 
other on reusable or nonreusable disk. 

Specifying Channel Program Blocks 

Channel program blocks (CPBs) are used to transfer data between buffers and 
direct-access secondary-storage devices. A CPB consists of 72 bytes of control 
information plus a work area the size of one buffer unit. One CPB is involved 
whenever the contents of a buffer unit are written on disk or read from disk. 
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Figure 6. Relative Record Numbers of Disk Message Queues Data Set Assigned Across Three Volumes 

CPBs that are not being used currently are queued in a free pool . When a CPB is 
to be used in writing data onto disk, TCAM "swaps" the CPB with a full buffer 
unit (the contents of which are to be written onto the disk); that is, the CPB work 
area is assigned to the available-unit queue, and a full buffer unit is assigned to the 
CPB to replace the work area. This swapping of units is accompUshed by chang- 
ing addresses internally; no movement of data occurs. 

When the CPB has been used in reading from disk, its full work area is swapped 
with an empty unit; that is, the CPB work area is assigned to the outgoing group 
of the Message Handler for the destination and is replaced by a unit from the 
available-unit queue. Thus, the unit pool always has the same number of units, 
even though they are not necessarily the same units that were originally in the 
pool. The number of work areas assigned to the CPB is also constant, although 
some of the work areas were once buffer units. This swapping feature saves time, 
because data need not be moved from the CPB unit into the buffer unit. 

Note: Swapping does not occur for units involved in a data transfer result - 
ing from disparity in size between origin buffers and destination buffers (for 
a discussion of such data transfer, see Other Buffer Design Considerations in 
the Designing Buffers chapter). In this case, data is moved from the CPB 
unit to an empty unit. 
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The number of CPBs in a TCAM system is specified by the CPB= operand of the 
INTRO macro. The number that should be specified must be determined experi- 
mentally and depends upon the message traffic during the peak period of activity 
in the TCAM system. The following formula may be used to determine initially 
how many CPBs to specify in a system: 

(2(BU)-H)m +r 
60 

where r is 1 if reusable disk and otherwise, m is the average number of mes- 
sages transmitted per minute during peak periods of activity, B is the number of 
buffers per message, and U is the number of units per buffer. The maximum 
number of CPBs that TCAM can use at any one time can be determined by 
adding the number of units per buffer for every destination QCB in the system 
(destination QCBs are generated when TERMINAL and TPROCESS macro 
instructions define stations and application programs to which messages may be 
directed). There is not much likelihood that TCAM will need this maximum 
number of CPBs. 

Although the minimum CPBs that may be specified is one, it is strongly recom- 
mended that the number of CPBs specified be equal to the maximum number of 
buffer units per buffer in the system, so that an entire buffer can be dispatched 
with a minimum number of operations. Specification of too few CPBs results in 
poor disk performance; messages are delayed while TCAM waits for CPBs to 
become available. Specification of too many CPBs results in waste of main 
storage; each CPB is 72 bytes plus the length of a buffer unit. 

How to determine if too many CPBs were specified on the CPB=: operand of the 
INTRO macro instruction: 

The type of queuing used by the CPB free pool is LIFO (last-in first-out), so that 
any unused CPBs at the bottom of the queue remain in the state they were in at 
TCAM initialization time (all zeros). 

The lEDFCPB field of the AVT points to the first entry in the CPB free pool; the 
thirteenth word of each CPB points to the next lower CPB entry on the queue. 
Consequently, a dump can be taken before the MCP is closed down, and by 
tracing the CPBs until one is found in the dump whose first few words are zeros, 
the user can determine if too many CPBs were specified. For instance, if 50 
CPBs were specified, and the first several words of CPB number 22 in the chain 
contained all zeros, then 29 of the 50 CPBs were not used. If the next execution 
of this same TCAM MCP incorporates the same technique of buffer allocation 
and is likely to be under the same Une and traffic conditions, specifying 25 CPBs 
should be adequate. 

How to Determine if too few CPBs were specified on the CPB= operand of the 
INTRO macro instruction: 

If, as a result of tracing CPBs in the dump discussed above, no CPBs are found 
whose first few words are zeros, one of two conclusions can be drawn: 

1. The exact number of CPBs required to avoid poor disk performance was 
specified(that is, all the CPBs were being used simultaneously on at least one 
occasion during the execution of this MCP, so that there was no delay in 
message traffic to or from disk). 

2. More likely, not enough CPBs were specified so that on one or more occasions. 
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TCAM had to wait until a CPB was available before it could place a message 
on (or remove it from) disk. 

The user should increase the number of CPBs the next time he executes this 
TCAM MCP under the same line and traffic conditions, unless he is changing 
from static to dynamic buffer allocation (if buffer allocation is static, there should 
be enough CPBs specified to handle a message). He can then determine, by the 
technique described in the previous section, whether the increased number of 
CPBs is too many (or, if the CPB at the bottom of the CPB free pool still does not 
contain all zeros, then specify an even larger number of CPBs the next time this 
MCP executes). 

Preformatting DASD Message Queues Data Sets 

Before the Message Control Program is started, TCAM expects message queues 
data sets on both reusable and nonreusable disk to be totally preformatted by the 
lEDQXA utility described in the chapter System Preparation . The records, into 
which each disk queue is segmented, should have the same length as that specified 
by the KEYLEN= operand of the INTRO macro. The name of the disk message 
queues data set is originally specified on the lEDQDATA DD statement for the 
lEDQXA program. The data set may be cataloged when the lEDQXA job is run. 

Message queues data sets located on disk should be preformatted before each cold 
restart of the MCP. 



Using Multiple-Arm Support 



Disk efficiency can be increased by spreading the disk message queues data set 
over several volumes (up to 16 volumes per disk data set). At initialization time, 
this is indicated by listing several volumes on the lEDQDATA DD card for the 
lEDQXA utihty. Each volume so indicated is initialized to contain one contiguous f 

extent of the data set. Each volume also contains identical amounts of record i 

space for the disk message queues. 

At TCAM open time, the old disk message queues data set is recognized as 
existing on several volumes. OPEN builds an input/output block (lOB) for each 
extent, permitting TCAM to issue several EXCP instructions, one per 
input/output block or extent. When the I/O Supervisor has several EXCP 
instructions to act upon, disk performance is improved by overlapping seek times 
on the various devices; that is, one drive can be seeking a cylinder while another 
drive is actively transferring data. Even better performance can be obtained by 
having the various volumes mounted on drives supported by different channels. 
This permits simultaneous search/read- write activity on more than one volume. 

Records are not assigned sequentially from beginning to end of the data set 

(although it was initially created sequentially). The record assignment algorithm 

uses the records of the first track, first cylinder, first extent, in a sequential 

manner. At the end of that track, instead of progressing to the next track of that 

same cylinder, records are assigned from the first track, first cylinder, of the 

second volume. Only one track of each volume is used before going to a new 

track on the next volume. This permits I/O requests to be made from more than 

just one volume, thus gaining the advantages of multiple EXCPs on several 

channels. The algorithm continues assigning the first track to new volumes until all 

volumes have used one track. Record assignment returns to the first volume, 

second track, first cylinder. Again, a new volume is used each time the end of a 

track is reached. This cycle repeats until the first cyUnder of all volumes is ^ 

assigned. Then the second cylinder is similarly assigned and so on until the entire i 

data set is filled. 
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This procedure is used for both reusable and nonreusable disk message queues. 

When reusable disk queuing is used, multiple-arm support increases the likelihood 
that one arm will be reading while another is writing, thus improving the efficiency 
of the system. However, this advantage may be offset by the need to construct an 
extra lOB and DEB extent for each volume, thereby increasing the amount of 
main storage required for the TCAM program. 



Reusable Disk Queues 



A reusable message queues data set can often handle the same amount of message 
traffic as a nonreusable message queues data set while occupying less disk space. 
A message queues data set located on reusable disk never runs out of disk space 
under normal conditions, and the TCAM system need never be closed down to 
replenish disk space for such a data set. In addition, when reusable disk queuing is 
used, messages for an inoperative terminal need not be trapped in the data set 
until the terminal is fixed, but may be sent to an alternate destination (specified by 
the ALTDEST= operand of a TERMINAL macro), which might be another 
terminal in close physical proximity to the first. This capabihty of automatically 
sending a message to an alternate destination is available only to the user of 
reusable disk queuing. A similar capabihty is provided by specifying a cascade Hst 
as a destination (see the description of the cascade Hst in Constructing the 
Terminal Table in the chapter Defining Terminal and Line Control Areas ). 

A reusable data set requires periodic reorganization. TCAM's method of reor- 
ganizing the reusable data set is illustrated in Figure 7. 

The data set as a whole (whether on one volume or 16) is divided into four equal 
zones (shown in Figure 7 as Zones A, B, C, and D). Messages are read into the 
four zones sequentially. By the time Zone D is full. Zone A has been prepared for 
reuse, and a cycle of use and reuse of the data set has been initiated. 

Figure 7 shows a 'ioadpoint" located half-way through each zone. Assume that 
the data set has been in use for some time; Zones A and B contain messages 
received relatively recently. When the loadpoint for Zone C is reached, a TCAM 
reorganization routine is automatically activated. This routine checks Zone A for 
messages that have not yet been sent or canceled. Such messages are placed on 
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Figure 7. Reorganizing a Reusable Data Set 
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the queue for the alternate destination specified by the ALTDEST= operand of 
the TERMINAL or TPROCESS macro for the original destination or on the 
queue for the original destination in the case of the LOGTYPE macro (these 
macros and their functions are described in the chapter Defining Terminal and 
Line Control Areas ). The alternate destination specified in ALTDEST= may be 
the original destination. If the alternate destination queue is located in the 
message queues data set currently being reorganized, the unserviced message is 
written in Zone C. If any destination QCBs have assigned next header records in 
Zone B, a canceled header is written in this location, thus updating next header 
positions to the current zone. This prevents a new message from being sent to its 
alternate destination because its header is too far back (by definition, this is an old 
message). By the time that the end of Zone D is reached. Zone A is ready for 
reuse; all unserviced, uncanceled messages that were in Zone A have been copied 
into Zone C (if the queue for the alternate destination is located in this data set) 
or copied into another data set. When Zone A is reached, its contents are overlaid 
with incoming messages. The cycle is repeated as each of the four loadpoints is 
reached. 

When a zone is reorganized and the unserviced messages for a particular destina- 
tion located in that zone are requeued for their alternate destination, they are 
assigned a message priority equal to or less than their original priority as specified 
for the alternate destination and are placed in its FEFO queue. For instance, if 
the original destination message had a priority of 8, and the available priority 
levels for the alternate destination are 9, 7, 5, and O, the message will be requeued 
with a priority level of 7. If the alternate also had a priority level of 8, the original 
message will be requeued at the same priority level. Messages are sent in the 
FEFO sending order usually in effect for messages having the same priority on a 
destination queue (see the discussion of message priority and queuing in the 
chapter Defining Terminal and Line Control Areas). Whether or not this 
modified message priority and sending scheme for requeued messages turns out to 
be an asset or a Uabihty to the reusable disk user depends upon his application. 

Note: When messages are moved in a zone reorganization, sequential order- 
ing is not maintained. 

The advantages of reusable disk queuing have already been mentioned. When the 
reorganization scheme just outlined is considered, certain disadvantages become 
evident: 

1 . The disk activity required during data-set reorganization may result in longer 
response times than would occur if nonreusable disk were used. Each message 
that is requeued must be read into main storage and rewritten in a message 
queues data set, and each dummy canceled message must be written from main 
storage into the data set on reusable disk. The longer that messages remain 
enqueued on the disk before being sent, the more likely it becomes that they 
will have to be reread and rewritten. Messages are more hkely to Unger in a 
reusable disk queue: when the transmission priority for the nons witched line to 
their destination is equal or receive rather than send (see the discussion of 
transmission priority in the chapter Defining Terminal and Line Control 
Areas ); when many stations are assigned to the same line; when traffic to a 
destination is heavy; when not enough CPBs are specified; when the destina- 
tion station is a start-stop rather than a BSC terminal; when the destination is 
an application program whose data sets are not open; and when a destination 
station on an Inward WATS line calls the computer infrequently. Terminal 
reliability is also a factor. If messages for a station must be intercepted by an 
operator command or by a HOLD macro because the station is inoperative. 
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response time will lengthen as the number of intercepted messages increases; 
this effect is compounded if the queue for the alternate destination specified for 
an intercepted station is also located in the reusable disk data set. 
2. TCAM's capability of retrieving messages that have already been sent (as 
described in the Message Retrieval section of the chapter Writing TCAM- 
Compatible Application Programs ) is limited when reusable disk queuing is 
used, because the original copy of a transmitted message is eventually overlaid 
by another incoming message. 

A serious problem may arise if a data set on reusable disk becomes full, that is, if 
TCAM's reusability routine is called to service a new zone, but has not yet 
completed servicing the previous zone. If there are more messages to be sent to 
alternate destinations than the reusability routine can handle, active disk records 
may be overlaid; when this happens, a logical read error occurs and TCAM 
terminates abnormally with a system ABEND code of 045 and with a code of 02 
or 03 in register 15. 

Heavy usage of reusable disk may be the result of either a sudden surge of incom- 
ing traffic for this queue type, or an accumulation of a large number of messages 
that must be routed to alternate destinations because their primary destinations 
are unable to accept them. 

In an attempt to prevent the need for abnormal closedown, TCAM requests 
cessation of incoming traffic, permitting send operations to have temporary 
priority to clear the data set of unsent messages. When the overlay danger is past, 
normal receive operations are resumed. If the temporary halt of receive opera- 
tions cannot prevent overlay of active records, the ABEND is issued. 

To reduce the frequency of this slowdown, the following steps may be taken: 

a. Format a larger reusable disk data set. As a rule of thumb, the data set should 
be at least large enough so that the longest message to that data set will span 
less than a fourth of the disk (less than one of the four zones). Otherwise, the 
internal TCAM zone reorganization routine may be unable to transmit unsent 
messages to their alternate destinations (because a zone for the abnormally 
long message has been overlaid, resulting in loss of header information needed 
to send this message to its alternate destination). 

b. Spread reusable disk data sets over several volumes (and ideally over several 
channels), thereby facilitating more rapid servicing of the zones by TCAM's 
reusability routine. 

c. If it is likely that a station will be intercepted or otherwise unable to receive for 
an appreciable percentage of the time, do not locate the destination queue for 
that station on reusable disk. 

d. To avoid trapping unsendable messages queued for a defective station, do not 
specify a station as its own alternate destination. 

e. To avoid accumulating messages queued to switched stations, exercise care in 
the specification of the DIALNO= and CLOCK= operands on the 
TERMINAL macro. By coding DIALNO=NONE, you prohibit the CPU from 
initiating a call to send messages to this station. The CLOCK= operand 
restricts the CPU to a single call every 24 hours. 

f . Consider the number of priority levels specified in the TERMINAL macro for 
each destination queue. Each priority level requires one record for the next 
header being sent to that destination. Thus, the more priorities that are as- 
signed, the larger the reusable disk needs to be. The number of priorities in the 
system should be less than one-eighth the total number of records on the disk. 
To determine the number of priorities, the following formula can be used: 
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Nonreusable Disk Queues 



T > 8(x + y) 

where T is the total number of records on the disk, x is the total number of 
TERMINAL, TPROCESS, and LOGTYPE macros coded in the terminal table, 
and y is the number of levels specified in every LEVEL = operand for every 
TERMINAL macro defined. 

g. Receive priority with too short an interval can cause messages to accumulate 
and create additional overhead. 

h. Finally, remember that the busier the lines, the larger the reusable disk data set 
should be; turnaround time for message transmission is adversely affected if the 
data set is not large enough for high-density message traffic. 

When using initiate mode or program-controlled interruption for input, be aware 
of the possibility that the first segment of a very long message can be overlaid 
before the last segment is received. 



For a TCAM MCP that must run continuously for an extended period of time 
with fairly heavy message traffic, the user would have to allocate more disk space 
if he used nonreusable queuing than he would if he used reusable queuing. In 
addition, a TCAM system using nonreusable disk queues must be closed down 
from time to time as the available space in the data set is exhausted. One great 
advantage that nonreusable disk queues have when compared with reusable disk 
queues is that system overhead is cut down during extended periods of high 
message traffic when nonreusable disk queuing is specified, because the data-set 
reorganization described above for reusable disk queues is not performed for 
nonreusable disk queues. Nonreusable disk queuing is attractive for applications 
in which many messages will remain enqueued for a long period of time before 
being sent; general criteria for estimating this likelihood are given above in the 
discussion of reusable disk queues. 



Main-Storage Queuing 



When a certain percentage of the records in a message queues data set on non- 
reusable disk has been used, a flush closedown (defined in the chapter Activating 
and Deactivating the Message Control Program ) is initiated by TCAM. The 
threshold percentage is specified by the THRESH= operand of the message 
queues DCB macro (described below) and should be based on a consideration of 
the maximum number of message units that will result from messages entered at 
stations and the number of units on the disk data set. If the data set fills before 
closedown is finished and wraparound of the nonreusable disk overlays the first 
record, the TCAM MCP will terminate abnormally with a system code of 045 and 
a value of 01 in register 15. Following the flush closedown, the data set must be 
reformatted (using the lEDQXA utility described in the chapter System 
Preparation ), and the system may be restarted by means of a cold restart. 



The main-storage message queues data set (if specified) is created at the time the 
INTRO macro is executed, when an area of main storage is allocated to the 
buffer-unit pool. The data set resides in the buffer-unit pool, which is described 
in the chapter Defining Buffers . Buffer units containing data directed to a 
destination queue in the main-storage data set are assigned directly to the appro- 
priate queue. Upon removal from the queue, the units are available for reuse. No 
data is moved iwhen units are placed on the queue; however, when the message is 
to be sent to its destination, it is copied from the enqueued units containing it into 
a buffer. The original copy is held in the queue until the message has been 
transmitted and any macros in the outmessage subgroup handling it have been 
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given an opportunity to check the message error record for the message; this is 
done so that the message header may be retrieved from the queue, if necessary. 

Because data in main storage is obtained and manipulated more rapidly than data 
stored on disk, during periods of high message traffic, messages directed to 
destinations whose whose queues are located in main storage will be received 
much more rapidly than would be the case if the queues for these destinations 
were located on disk. Because allocation and deallocation of units for the main- 
storage data set is dynamic, the data set is essentially ''reusable." 

When a message queues data set is located in main storage without disk backup, 
sufficient main storage must be allocated to the data set to handle peak message 
traffic. The MSUNITS= operand of the INTRO macro specifies the maximum 
number of units that can be assigned at any one time to the main-storage message 
queues data set. If buffer units containing part of an incoming message are 
inserted into the destination queue, causing the number specified by MSUNITS= 
to be exceeded, bit 16 is turned on in all message error records in the system. The 
first unit of the buffer is placed in the queue; all the other units of the buffer are 
lost. If this was not the last buffer in the message, any error-handling macros 
(coded in the inmessage subgroup of the Message Handler for this line group) that 
test bit 16 of the message error record are activated. For example, the user might 
code a MSGGEN or ERRORMSG macro to advise the terminal operator or an 
application program that message segments are being lost because of a lack of 
available main-storage units. The operator or application program could then 
slow down incoming message traffic using appropriate operator commands or 
network control macros until sufficient main-storage units are available. If the 
segment rejected was the last segment, the entire message (except for the first 
unit) is lost; in this case the user may test bit 16 of the message error record when 
another message is handled by this or another Message Handler. 

The first unit of a message that is lost because of a lack of main-storage units is 
always enqueued in its proper destination queue. When this unit is processed by 
the outgoing group of the Message Handler for the destination station, bit 16 of 
the message error record for this message is turned on. In his outmessage sub- 
group, the user may code error-handling macros to test bit 16. For example, he 
might code an ERRORMSG macro that would return the unit to the originating 
station together with a request that this message be retransmitted. 

In the event that there is not even enough main-storage space available to permit 
the first unit of a message to be enqueued (that is, if enqueuing the unit would 
cause the value specified in the MSUNITS= operand to be exceeded), TCAM 
nevertheless enqueues the unit. In addition, TCAM refuses to accept any more 
incoming messages (these messages are not lost) until the number of units in the 
main-storage data set falls to or below the level specified by the MSMIN= 
operand of the INTRO macro. 

TCAM's only criterion in determining whether units are available for main- 
storage queuing is the number specified by the MSUNITS= operand of the 
INTRO macro. It is up to the user to specify a satisfactory number of main- 
storage units for his system. If he does not, and if no disk backup is provided, 
throughput will suffer because fewer incoming messages will be accepted, and 
some message segments may be lost. 

p TCAM provides the user of main-storage queues with a means of informing 

himself when the main-storage data set is in danger of running out of units. In the 
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MSMAX= operand of the INTRO macro, the user may specify a percentage of 
his main-storage data set units (that is, a percentage of the number specified in the 
MSUNITS= operand of INTRO); when this percentage of units is enqueued, bit 9 
of all message error records in the system is set. The user may code a MSGGEN 
or ERRORMSG macro in his Message Handlers to check this bit and inform the 
operator or an application program to slow down invitation until a suitable 
number of enqueued messages have been sent to their destinations. Since mes- 
sages for inactive application programs are maintained on main-storage queues, 
the user may also activate the application program and allow those enqueued 
messages to be sent. The MSMIN= operand of INTRO also specifies a percent- 
age of the total number of units available for main-storage queuing. When the 
percentage of units enqueued in the main-storage data set falls below that speci- 
fied by MSMIN=, bit 8 is set on in all message error records in the system. The 
user may code a MSGGEN or an ERRORMSG macro in his Message Handlers to 
test this bit and inform the operator or an application program that there is no 
longer a shortage of main-storage units, so that normal invitation may be resumed. 

When the percentage of enqueued units falls below that specified by MSMAX=, 
bit 9 is turned off in all message error records. When the percentage of enqueued 
units rises above that specified by MSMIN=, bit 8 is turned off in all message 
error records. 

TCAM also permits the user (who has one or more destinations using main- 
storage-only queuing) to inform himself when a certain number of messages are 
queued for output to a specific destination. See the description of the THRESH = 
operand of the FORWARD macro for a more complete description of this facility. 

Neither the intercept function (see the description of the HOLD macro) nor the 
retrieve capabiHty (see the description of the POINT macro) can be used for 
messages queued in main-storage-only queues. The ERRORMSG and 
REDIRECT macros provide Umited retrieval capability when certain errors (such 
as transmission errors, as detected by the EOB checking f acihty provided by the 
STARTMH macro) occur. 

A message queues data set located in main storage without disk backup cannot be 
checkpointed; if the TCAM system closes down or fails, all data in the data set is 
lost. 

Instead of specifying a main-storage message queues data set with no disk backup, 
the user may specify a main-storage data set having backup on reusable or non- 
reusable disk. Main-storage queuing with disk backup combines advantages of 
disk and main-storage queuing, and avoids certain of the problems associated with 
the other queuing methods. Data directed to a main-storage queue with disk 
backup is never lost because of unavailability of main-storage units, and TCAM 
will accept messages when the main-storage data set is full. TCAM's message- 
interception and message-retrieval functions may be utilized, and closedown and 
restart of the system without loss of data is possible. Response time is better than 
with disk queuing, because most outgoing messages do not have to be read from 
disk. 

When main-storage queuing with disk backup is used, TCAM copies each unit 
arriving at a main-storage queue onto disk. Copying involves a movement of all 
data in the unit and a writing operation. When the number of units specified in 
the MSUNITS= operand of the INTRO macro is enqueued in main storage (when 
the main-storage queues will accept no more units), data is not lost as it is whe^n 
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main-storage-only queuing is specified; instead, the contents of incoming units are 
written directly onto disk. No bit in the message error record is set when main- 
storage units are exhausted, and invitation is not suspended. The user may code 
the MSMAX= operand of the INTRO macro to warn him that the number of 
units enqueued in main storage is approaching the maximum permitted, and he 
may use the MSMIN= operand of INTRO to inform him when the number of 
units enqueued in main storage has fallen to a safe level. 

Outgoing messages are sent from the main-storage queue when they are on this 
queue; otherwise they are brought in from disk and sent. When a message is sent 
out from main storage, its copy on disk is marked serviced. 

The TCAM intercept function (using the HOLD macro) and retrieve function 
(using the POINT macro) may be implemented when main-storage queuing with 
disk backup is used (where access is to the disk queues). 

Main-storage queuing with backup on disk uses more main storage than disk 
queuing and results in a longer response time than would be the case if main- 
storage queuing with no disk backup were specified (because each message must 
be completely copied onto disk before it can be sent to its destination). Yet this 
method of queuing combines many of the attractive features of the other methods, 
and for many applications it provides an acceptable compromise between the 
speed of main-storage-only queuing and the reliability of disk queuing. 

Specifying One or More Queuing Methods 

The user may specify up to three message queues data sets for his TCAM system. 
One of these- resides in main storage, another on reusable disk, while a third is 
located on nonreusable disk. Taken singly or in combination, these three possible 
data sets provide the five queuing methods discussed. For main-storage-only 
queuing, a main-storage data set is needed. Reusable and nonreusable disk 
queuing each require a data set. If the user wishes to implement main-storage 
queuing with reusable disk backup, he must define two data sets — one in main 
storage and the other on reusable disk. Two data sets are also required to support 
main-storage queuing with backup on nonreusable disk. 

A TCAM system having two message queues data sets, one in main-storage and 
one on reusable disk, will support three types of queuing: main-storage-only 
queuing, reusable disk queuing, and main-storage queuing with backup on reus- 
able disk. The type of queuing used for a particular message in this system 
depends upon the message's destination. The QUEUES = operand of the 
TERMINAL or TPROCESS macro defining a remote station or an appUcation 
program specifies the type of queuing for messages destined for that station or 
application program. In the system being considered, messages sent to a terminal 
whose TERMINAL macro specified QUEUES = MO would be queued in main 
storage only. Messages sent to a terminal whose TERMINAL macro specified 
QUEUES =DR would be queued on the reusable disk only. Messages sent to a 
terminal whose TERMINAL macro specified QUEUES = MR would be placed on 
a queue in main storage if possible, and would also be placed on a queue in the 
reusable disk data set. Such messages would be retrieved and sent from the 
main-storage queue, if possible, or from the disk queue. 

The number of data sets that must be defined depends upon the type of queuing 
desired, which in turn depends upon the application. As an example, consider a 
savings bank inquiry application in which short incoming messages (consisting 
perhaps of an account number, a transaction amount, and a transaction code) are 
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sent to an application program, and long response messages are returned by the 
application program. The TCAM user with such an appHcation might wish to use 
main-storage-only queuing for the inquiry messages (since they are short), and 
disk queuing for the response messages (since they are long). In this way, he 
could take advantage of the speed of main-storage-only queuing for his short 
input messages without giving up the main storage required if main-storage 
queuing were used for his long response messages. To implement his queuing 
scheme, this user would have to define two data sets — one in main storage, and 
one on disk. 

CheckHsts follow for specifying the three types of message queues data sets 
supported by TCAM. are discussed elsewhere in this publication. Note that no 
DD statement or DCB macro is required in defining a main-storage message 
queues data set, but that both a DD statement and a DCB macro must be issued in 
defining a message queues data set on either reusable or nonreusable disk. The 
DCB macro for a message queues data set on disk and the DD statement for such 
a data set are described in the next two sections. 



Checklist for Main -Storage Data Set 



Macro 
DD Card 

INTRO 



Operand 



MSUNITS=integer 



Comments 

Specifies the maximum number of main-storage buffer units that 
may be used for queuing. 



INTRO 



MSMAX=integer 



integer is a percentage of the number of units specified in the 
MSUNITS= operand; when this percentage of units is enqueued 
in the main-storage message queues data set, a bit is set in each 
message error record in the system to warn the user that his data 
set is nearly full. 



INTRO 



INTRO 



MSMIN=integer 



DISK= 



|NO) 
\YESJ 



When the percentage of the number of units specified by the 
MSUNITS= operand falls below that specified by MSMIN=, a 
bit is set in every message error record in the system. This 
operand may be used to inform the user that his main-storage 
message queues data set is no longer crowded. 



Specify NO if no message queues data set is to be provided on 
disk. Specify YES if the system will have a message queues data 
set on disk. 



TERMINAL 

or 
TPROCESS 



QUEUES=^MR 

MN 



Code MO for each station or appUcation program with queues 
to be located in main storage only; code MR if backup is to be 
provided on reusable disk; code MN if backup is to be provided 
on nonreusable disk. 



( 



100 OS/MFT and OS/MVT TCAM Programmer's Guide 



Checklist for Reusable Disk Data Set 



Macro or 
DD Card 


Operand 


DD 

Statement 




Message 

Queues 

DCB 




INTRO 


DISK=YES 


INTRO 


CPB=integer 


TERMINAL 

or 

TPROCESS 


QUEUES=|DRl 
\MRf 



Comments 



One needed; see DD Statements for Message Queues Data 
Sets . 



One needed; see next section. 



Specifies the nonzero number of channel program blocks to be 
provided for transfer of data between buffers and the disk; see 
Specifying Channel Program Blocks in this chapter. 



Code DR for each station or application program with queues to 
be maintained on reusable disk only; code MR for queues to be 
maintained in main storage with reusable disk backup. 



Checklist for Nonreusable Disk Data Set 

Macro or Operand Comments 

DD Card 



DD 

Statement 




Message 

Queues 

DCB 




INTRO 


DISK=YES 


INTRO 


CPB= integer 


TERMINAL 

or 

TPROCESS 


QUEUES = J DN ) 
IMN) 



One needed; see DD Statements for Message Queues Data 
Sets. 



One needed; see next section. 



Specifies the nonzero number of channel program blocks to be 
provided for transferring data between buffers and disk; see 
Specifying Channel Program Blocks in this chapter. 



Code DN for each station or 

appUcation program with queues to be maintained on nonreusa- 
ble disk only; code MN for each station with queues to be main- 
tained in main storage with nonreusable disk backup. 
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Message Queues DCB Macro 



The message queues DCB macro 

• defines a message queues data set residing on reusable or nonreusable disk; 

• specifies the location of the data set; 

• specifies the percentage of records in a nonreusable disk data set to be filled 
before a flush closedown is initiated; 

• is not issued for a message queues data set residing in main storage. 

The message queues DCB macro defines a data control block for a message 
queues data set. Parameters based on the keyword operands specified in the 
macro are included in the data control block. One message queues DCB macro is 
required for a message queues data set residing on reusable disk, and one is 
required for such a data set residing on nonreusable disk. The macro generates no 
executable code. 

The message queues DCB macro has the following format: 



Name 


Operation 


Operands 


diskdcb 


DCB 


keyword operands 



diskdcb 



Function: Specifies the name of the macro instruction and the name of the data 

control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



keyword operands 



Function: Specifies the operands that can be used. 

Format: The operands may be specified in any order and are separated by 

commas with no intervening blanks. 

Notes : The operands for the message queues DCB macro instruction are described 

below. 

When a parameter can be provided by an alternate source, a symbol appears in the 
alternate source entry for the operand. When there is no alternate source (that is, 
the parameter must be specified by the operand), the alternate source entry states 
None . The symbols have the following meanings: 

Symbol Explanation 

DD The value of the operand can be provided at execution time by the data 

definition(DD) card for the data set. 

OE The value of the operand can be provided by the problem program any 

time up to and including the data control block exit at open time. 



PP The value of the operand can be provided by the user's problem 

program any time before the data control block exit at open time. 



i 
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DSORG=TQ 



MACRF=(G,P) 



DDNAIVfE=:ddnanie 



If DD is specified, OE or PP may also be used. OE is specified, PP may also be 
used. For information on providing parameters by DD, see DD Statement for 
Message Queues Data Sets . For information providing parameters by DD and 
OE, see Modifying the Data Control Block in the OS publication Data Man- 
agement Services . The section Processing Program Description , in the same 
publication, describes the data control block exit that can be taken when OE is 
specified. 

The formats of macro illustrations, the symbols used in them, and rules for the 
interpretation of operand descriptions are all provided in Appendix A . 



Alternate Source: None. 

Function: Specifies that the data set organization is that for the message queues 

or checkpoint data set. 

Default: None. This operand is required. 

Format: DSORG=TQ 



Alternate Source: None. 

Function: Specifies that access to the data set is gained with GET and PUT 

macro instructions. 

Default: None. This operand is required. 

Format: MACRF=(G,P) 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



OPTCD= 



{^} 



Alternate Source: DD, PP, OE. 

Function: Specifies the location of the data set. 

Default: None. This operand is required. 

Format: L or R. 

Notes: L specifies that the data set is to be on nonreusable disk. R specifies that 

the data set is to be on reusable disk. 



EXLST=nanie of list 



Alternate Source: PP. 

Function: Specifies the address of the problem program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This operand is required if user label, data control block, user ABEND, or 

block count exits are required. The list must start on a fuUword boundary. Its 

format and contents are shown in Data Management Services . The user ABEND 

exit is discussed in the last section of this chapter. 
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THRESH=integer ^ 

Alternate Source: DD, OE, PP. ^ 

Function: Specifies the percentage of the nonre usable disk message queue 

records to be used before a flush closedown of the system is initiated. 

Default: For reusable disk queues, specification optional. For nonreusable disk 

queues, 95. 

Format: Unframed decimal integer. 

Maximum: 100 

Notes: This operand is meaningful for nonreusable disk queues only. 

DD Statements for Message Queues Data Sets 

One DD statement is needed for each disk message queues data set. The format 
of this DD statement is as follows: 

//ddname DD DSNAME=anyname,DISP=OLD 

where ddname is the name specified by the DDNAME = operand of the DCB 
macro for this data set, and anyname is the name of the data set as specified by 
the DSNAME= operand of the lEDQDATA DD card for the lEDQXA utility 
used to Preformat disk message queues. If the data set is not cataloged, the 
UNIT= and VOLUME= operands must be included in the DD statement for the 
disk message queues data set. 

The OPTCD= and THRESH = operands of the message queues DCB macro may 

be omitted from the DCB macro and specified at execution time by coding the ^ 

DCB parameter of the DD statement for the message queues data set; that is: {| 

DCB=(OPTCD= JlI ) 

PI 

or 

DCB=(THRESH=n) 

Both operands may be specified by coding 

DCB= ( OPTCD= Jl) , THRESH^n ) 

Fi 

These operands are explained in the preceding section. 

No DD statement is issued to define a message queues data set in main storage. 



Checkpoint Data Set 



The TCAM checkpoint facility makes records of the MCP environment from 
which restart can be made in case of closedown or system failure. This facihty is 
described in the section Using TCAM Service Facilities . 

The checkpoint data set consists of checkpoint records that are maintained and 
stored on a direct-access storage device. A DCB macro instruction must be issued 
to define the data control block for the checkpoint data set if the checkpoint 
facility is to be used. The DD statement associated with the new checkpoint data 
set must allot space for these records on the direct-access device used. The 
direct-access device may be either an IBM 23 1 1 Disk Storage Drive, an IBM 23 14 
Direct Access Storage Facility, or an IBM 3330 Disk Drive. 



c 
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chkptdcb 



keyword operands 



Checkpoint DCB Macro 

The checkpoint DCB macro 

• defines a checkpoint data set residing on a direct-access storage device. 

The checkpoint DCB macro has the following format: 



Name 


Operation 


Operands 


chkptdcb 


DCB 


keyword operands 



Function: Specifies the name of the macro instruction and the name of the data 

control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the operands that can be used. 

Format: The operands may be specified in any order and are separated by com- 
mas with no intervening blanks. 
Notes: The operands for the DCB for the data set are described below. 

When a parameter can be provided by an alternate source, a symbol appears in the 
alternate source entry for the operand. When there is no alternate source (that is, 
the parameter must be specified by the operand), the alternate source entry 
specifies None . The symbols have the following meanings: following meanings: 

Symbol Explanation 

DD The value of the operand can be omitted from the DCB macro and 

provided at execution time by the data definition (DD) card for the 
data set. 

PP The value of the operand can be provided by the user's problem 

program any time before the data control block exit at open time. 

OE The value of the operand can be provided by the problem program any 

time up to and including the data control block exit at open time. The 
formats of macro illustrations, the symbols used in them, and rules for 
the interpretation of operand descriptions are all provided in Appendix 
A. 



DSORG=TQ 



Alternate Source: None. 

Function: Specifies that the data set organization is for the message queues or 

checkpoint data set. 

Default: None. This operand is required. 

Format: DSORG=TQ 
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IVIACRF=(G,P) 



DDNAME=ddname 



OPTCD=C 



EXLST=address 



BLKSIZE=number 



Alternate Source: None. 

Function: Specifies that access to the data set is gained with GET and PUT 

macro instructions. 

Default: None. This operand is required. 

Format: MACRF=(G,P) 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



Alternate Source: PP, OE, DD. 

Function: Specifies that the data set is for checkpoint records. 

Default: None. This operand is required. 

Format: OPTCD=C 



Alternate Source: PP. 

Function: Specifies the address of the problem program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: This Ust must be provided if user label, data control block, or user ABEND 

exits are required; it must start on a fuUword boundary. The format and contents 

of the list are shown in the Data Management Services publication. The user 

ABEND exit is discussed in the last section of this chapter. 



Alternate Source: DD 

Function: Specifies the size in bytes of the environment checkpoint records on 

disk. 

Default: 300 

Format: Unframed decimal integer. 

Minimum: 300 

Maximum: 3520 

Notes: If a number less than 300 or greater than 3520 is specified, 300 or 3520 

respectively is used, and a message notifying the programmer is generated on the 

system output device. A larger record size may use disk space more efficiently, 

but the work area would take up more main storage. These two factors must be 

taken into account to arrive at the best BLKSIZE for a given application. 



DD Statement for the Checkpoint Data Set 

One DD statement must be issued for the checkpoint data set. If DISP=NEW is 
coded, this statement must allocate space on DASD for all records in the check- 
point data set. A formula for allocating sufficient space is given in How to Get 
the TCAM Checkpoint Facility in the chapter Using TCAM Service Facilities . 
The DISP= parameter must be coded DISP=OLD for a warm restart and may be 
coded either DISP=OLD or DISP=NEW for a cold restart. If DISP=NEW is 
coded, STARTUP=CY is assumed for the INTRO macro instruction (or 



( 
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Log Data Sets 



STARTUP = CI Y, if I coded in the STARTUP = operand), regardless of what is 
coded for STARTUP = at assembly time or at WTOR response time. (The 
disposition parameter of DISP= also may be coded.) Any incremental quantity 
requested on the SPACE= parameter is ignored. 

The OPTCD= operand of the checkpoint DCB macro may be specified at execu- 
tion time by coding the DCB parameter of the DD statement for the checkpoint 
data set as DCB=(OPTCD=C). 

A typical DD card used for initial allocation is: 

//TPCHKPNT DD DSNAME=CPDS , UNIT-23 1 1 , * 

// V0LUME=SER=1 1 1 1 1 1 , * 

// SPACE=(TRK,( 3 ) ), * 

// DISP=(NEW,CATLG) 

Note: The step containing the DISP=(NEW,CATLG) operand must terminate 
normally for the deallocation routine to perform the catalog function. If 
such a step is halted by SYSTEM RESET or Master Check, the catalog is 
not updated. The next use of the data set, with DISP=^OLD coded, must 
either supply the UNIT= and VOL=SER= operands, or the name must have 
been entered into the catalog using the CATLG command of the 
lEHPROGM system utility. 

A typical DD card used for the same (cataloged) checkpoint data set after initial 
allocation is: 

//TPCHKPNT DD DSNAME^CPDS , DISP=OLD 

The data set does not have to be cataloged. If it is not cataloged, the data set is 
allocated by specifying DISP=(NEW,KEEP), and subsequent uses of the data set 
must contain the UNIT= and VOL=SER= keyword operands to provide the 
information that would otherwise be in the catalog. 

Note: There is no utility job to format a checkpoint data set. It is format- 
ted by OPEN at each cold restart. 



A log data set consists of messages or message segments placed on a secondary 
storage device for accounting purposes. TCAM's support of the logging function 
is described in the Using TCAM Service Facilities chapter and in the descrip- 
tions of the LOG and LOGTYPE macros. The TCAM logging facility is optional. 

One log data set should be defined for each secondary storage device on which 
messages or message segments may be logged. A log data set is defined by a 
BSAM DCB macro that is issued with the DCBs defining the line group data sets, 
the message queues data sets, and the checkpoint data set. The BSAM DCB 
macro is described in the Supervisor and Data Management Macro Instructions 
publication. 
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User ABEND Exits 



In the BSAM DCB macro for a log data set, the user should code the following 
operands: 

Operands Comments \ 

DSORG=PS 

MACRF=W 

DDNAME=symbol 

BLKSIZE=keylen Replace keylen with the value specified 

in the KEYLEN= operand of the INTRO 

macro. 
RECFM=F 
NCP=integer Replace integer with the maximum number 

of buffer units that may appear in a 

buffer. 

The SYNAD= address operand of the BSAM DCB macro, where address is the 

name of a user-specified, error-analysis routine to be given control when an 

uncorrectable I/O error is detected, should also be coded. The error routine must 

conform to the standards set forth in the discussion of this operand in the 

Supervisor and Data Management Macro Instructions publication. Upon return 

from the error-analysis routine, the log function continues as if no error had been 

encountered. All indications of the I/O error must be removed from the DCB, 

(that is, reset the first two bits of the IFLGS field of the data control block to 

zeros — see the EXCP macro instruction in the System Programmer's Guide); if an 

I/O error is still indicated the MCP will terminate abnormally when the next 

WRITE is issued. The format of the BSAM DCB is described in the System 

Control Blocks publication. If this operand is not specified, the MCP terminates 

abnormally when a permanent I/O error occurs during the logging operation. The 

UNIT= parameter of the DD statement associated with each log DCB macro 

should specify the address of the appropriate secondary storage device. ,f 

The DCB macros for the Une group data sets and for the message queues data sets 
permit specification of a user-written routine to be given control if an OPEN 
macro fails to open the data set for which the DCB macro is coded. The user 
routine is specified by coding a special entry in the problem-program exit Ust 
named in the EXLST= operand of the appropriate DCB macro. (The format and 
contents of the problem-program exit list are shown in Data Management 
Services .) The special entry, called the user ABEND entry, consists of a one-byte 
code of X*OE' followed by the three-byte address of the user routine. 

If the OPEN macro for a particular data set fails to execute properly, and if a user 
ABEND entry is included in the EXLST= operand of the DCB macro for the data 
set, the user routine is given control. The user routine should save and restore 
registers. When control is passed to the user routine, the general registers contain 
the following information: 
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Register Contents 

Error code 

1 Options available to the user ABEND routine 
2-13 Contents before execution of the OPEN macro 

14 Return address (must not be altered by the exit routine) 

1 5 Address of user-routine entry point 

The error code, which occupies the right-hand byte of register (the other three 
bytes are set to 0) tells the user the reason why the OPEN failed. Possible error 
codes and brief explanations are described in the publication TCAM Level 4 
Component Release Guide. 

The error code is also included in a message directed to the system console when 
the OPEN fails. This message, which is sent even when no user ABEND routine 
is specified, has the following format: 

IED008I TCAM OPEN ERROR xxx-y IN DCB dcbname descriptor 

Here, xxx-y is the code referred to in the list of error codes, dcbname is the name 
of the DCB macro for the data set that could not be opened properly, descriptor 
is a single word describing the type of error. This message is discussed in the 
TCAM Level 4 Component Release Guide document. 

The following instructions may be coded in the user ABEND routine to return 
control to TCAM: 

L 13,4(13) 

RETURN ( 14, 12 ),T,RC=( 15 ) 

If an OPEN macro fails to execute properly and no user ABEND exit is provided, 
TCAM issues an ABEND macro to terminate the MCP task. 

Before control is passed to the user ABEND routine, TCAM sets the bits in the 
right-hand byte of register 1 to indicate to the ABEND routine what courses of 
action it may take. The code in register 1 indicates possible user options; the 
TCAM Open routines are set up to work properly if any of the courses of action 
indicated by the code in register 1 are taken. It is recommended that the user 
ABEND routine restrict its activities to the options indicated in register 1 . Possi- 
ble user ABEND alternatives and the codes associated with them are shown 
below. 

Code in 

Register 1 Permissible User Options 

X*03' 1. You can abnormally terminate the MCP job — either by 

issuing an ABEND macro in your subroutine, or by placing 
a return code of X'02' or higher in the right-hand byte of 
register 15 and returning control to TCAM. 
2. You can tell the TCAM Open routine to make no further 
attempt to open this data set, but to pass control to the next 
instruction in the MCP. This is done by placing a return 
code of X'OO' in the right-hand byte of register 15 and re- 
turning control to TCAM. In this case, your MCP will run 
with restricted capabilities, since it will not be able to use 
this data set. 
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X'07' 1 . Same as Option 1 for X'03' code. 

2. Same as Option 2 for X'03' code. 

3. In activating the lines in a line group data set, a TCAM 
Open routine has found a Une on which there are stations 
incompatible with those found on a previous line within the 
same line group. (See Characteristics of a Line Group in 
the chapter Defining the MCP Data Sets for the common 
characteristics that stations and Hues in the same hne group 
must have.) When such a line is found, TCAM stops activat- 
ing lines in the line group. By placing a return code of X'OT 
in the right-hand byte of register 15 and returning control to 
TCAM, you direct the Open routine to open a modified Une 
group data set consisting of only those lines that had been 
activated when the hne having incompatible stations was 
encountered. In this case, messages directed to stations or 
lines that were not activated will be enqueued in a message 
queues data set, but will never be sent to these stations. 

If the user specifies a return code of X'OT in register 15 and the option code 
passed to him in register 1 was X*03', TCAM immediately takes the ABEND exit 
again; unless the user routine has code providing for this possibihty, a loop will 
result. 

For more information on the DCB exit hst and how it is specified, see Data 
Management Services. 



/I 
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Activating and Deactivating the Message Control Program 

This chapter describes how to start and restart the TCAM Message Control 
Program, how to initiaUze and activate the TCAM data sets, and how to close 
down the TCAM MCP. 

Starting and Restarting TCAM 

The Message Control Program is assembled, link-edited, and executed like any 
other problem program running under an OS system. Sample Job Control Lan- 
guage for assembUng, Unk-editing, and executing the MCP is given in the chapter 
Putting the MCP Together. 

The TCAM MCP may be started or restarted by placing the job control state- 
ments for the EXECUTE step in the card reader and activating an OS 
Reader/Interpreter (by a START command issued at the system console) to read 
the JCL into the system. Another way to start or restart the MCP is to issue a 
START command naming a cataloged procedure that causes the MCP to be 
executed. The chapter on putting the MCP together contains sample code and job 
control statements for implementing both types of start-up. The various types of 
restart available to the TCAM user are described in the TCAM 
Checkpoint /Restart Facility section of the chapter Using TCAM Service 
Facilities . 

Initialization and Activation 

The INTRO, OPEN, and READY macros are issued as a group; together they 
constitute the data-set initialization and activation section of the Message Control 
Program. This section must precede the Message Handler sections of the MCP 
(see the chapter Pw/Zmg the Message Control Program Together). When the 
INTRO, OPEN, and READY macros have been executed, the TCAM system is 
ready to handle message traffic. 

As the first macro executed in the Message Control Program, INTRO expects to 
get control from OS job management. INTRO estabHshes standard entry linkage 
with job management, chains save areas, provides addressability, and saves the 
start parameter Ust pointer. To insert user-written code (which must not contain 
any TCAM macros) before INTRO, the Message Control Program (that is, the 
code beginning with INTRO) should be called as a subroutine of the inserted user 
code; register 15 should contain the address of INTRO, register 14 the address to 
which the MCP returns upon termination of TCAM, register 13 the address of a 
standard 18-word save area, and register 1 the start parameter Hst pointer as 
originally passed in register 1 from job management. 

If the user desires to refer to the PARM field of the EXEC job control statement, 
he may either use the register 1 pointer as passed by job management (before 
INTRO execution) to find the PARM field; or (after INTRO execution) this same 
value (in register 1) is stored by INTRO in a local constant area, a fullword tagged 
lEDSPLPT. 

The INTRO macro also creates the address vector table (which is the primary 
control block of the TCAM system) wherein many system variables are defined. 
When INTRO is executed, it optionally provides for dynamic redefinition of many 
of these system variables by interpreting the operator's response to a WTOR 
message. Once the system variables are defined in the address vector table. 
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INTRO continues with system initialization, creating buffers and trace tables, and 
formatting control blocks. 

The OPEN macro completes the initialization and activation of the TCAM data 
sets. The TCAM data sets that must be activated in the MCP by OPEN macros 
are those for the message queues, the line groups, the message logs, and check- 
point. 

Each data set that is used by the MCP can be opened by a separate OPEN macro, 
or all data sets of the same type (for example, all line group data sets) can be 
opened with one OPEN. If used, the message queues data sets must be opened 
first, and the checkpoint data set must be opened next. Opening a line group data 
set causes all lines in the line group to be prepared for operation; the lines option- 
ally may be prepared for message transmission at this time, or activation may be 
deferred until later (the line is opened idle and later started by the STARTLINE 
operator command). 

The READY macro must be the last instruction in the initialization and activation 
section of the MCP. When READY has executed, the system is prepared to 
handle message traffic. The expansion of this macro causes a branch to the 
internal routine that supports the MCP, where receipt of the first message is 
awaited. When the first message is received (either from a terminal or an applica- 
tion program), control is transferred to the MH section of the MCP for handling 
the message. 

Once the MH sections are initially entered after the execution of the READY 
macro, execution of user-specified code in the MCP is restricted to the Message 
Handlers; that is, the MH sections are continually reentered to handle messages /f 

entering and leaving the computer as long as the MCP is active. Accordingly, any ^ 
user code must either be within or be branched to from a Message Handler. User 
code cannot branch between Message Handlers. (See the User Code in a 
Message Handler section of the chapter De5/^«/«g the Message Handler.) 

For a sample MCP initialization and activation routine, see the last section of this 
chapter. 

In addition to initial start-up of the TCAM system, as described above, TCAM 
provides for three types of restart following system closedown or failure. These 
are discussed in Restart of the chapter Using TCAM Service Facilities. 



( 
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INTRO 



The INTRO macro 

• creates the address vector table (the primary control block in the TCAM 
system); 

performs the bulk of TCAM system initialization; 

estabUshes addressabihty and entry linkages for the Message Control Program; 
specifies the name of the Message Control Program; 

specifies the number of channel program blocks to be provided for transferring 
data between buffer units and queues maintained on disk; 
specifies the maximum number of command input blocks that may be used at 
any one time to contain operator commands entered at the system console; 
identifies the primary operator control terminal; 
specifies a character string used to identify operator commands; 
specifies the size of buffer units; 

specifies the maximum number of units that may be assigned to a main-storage 
message queues data set; 

provides the user with a means of determining when his main-storage message 
queues data set is nearly full, and when this condition of impending fullness has 
abated; 

identifies the station or application program to which messages having an 
invaUd destination are to be forwarded; 

specifies which user registers are to be saved when in-Hne user code is located 
in an inheader or outheader subgroup that may handle multiple-buffer headers; 
specifies the length of the system interval; 
specifies the interval between environment checkpoints; 
specifies the number of environment checkpoint records to be retained at any 
one time; 

provides system optimization by specifying that unnecessary options are to be 
omitted; 

specifies the type of restart to be performed following system closedown or 
failure; 

specifies a password that must be coded in certain appUcation-program macros 
that affect operation of the MCP; 
provides for inclusion of various debugging facilities; 

specifies whether a special operator awareness message is to be displayed at the 
primary operator control station whenever a station fails to respond to polling. 

• specifies the number of concurrent broadcast requests, the number of common 
data areas, and the size of each data area. 

TCAM reUes upon the INTRO macro to supply information for defining and 
initializing a variety of TCAM functions. The operands of INTRO provide 
information concerning data-set definition (DISK-, CPB=, MSUNITS=, 
MSMAX=, MSMIN=), buffer definition (KEYLEN=, LNUNITS=), the opera- 
tor control facility (CIB=, PRIMARY=, CONTROL==), the Message Handlers 
(DLQ=, USEREG=), line control (INTVAL=), the TCAM checkpoint/restart 
facility (CPINTVL=:, CPRCDS=, STARTUP=^, RESTART «=, CKREQS==:), 
system optimization (CPB=, DISK=, FEATURE=, LINETYP=:), network 
configuration (PASSWD=), debugging aids (TRACE=, TREXIT=, DTRACE=:=, 
CROSSRF=, TOPMSG=, COMWRTE=), and the on-line test facility 
(OLTEST=). Sections devoted to each of the above topics are located elsewhere 
in this publication. The user may read the description of the INTRO macro for 
general information before he is f amiUar with the TCAM functions to which the 
operands refer, but he should not attempt to code INTRO operands until he has 
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read the discussion of the particular function he wishes performed. In general, the 
following operand descriptions will refer the reader to the discussions of the 
functions of the operands. 

TCAM provides the user with the abihty to replace, at INTRO execution time, 
values specified at assembly time by certain operands of the INTRO macro, and to 
provide values for INTRO operands that were omitted at assembly time. 

At the time INTRO is executed, it may cause the following WTOR message to 
appear on the system console: 

nn IED002A SPECIFY TCAM PARAMETERS 

This WTOR message is issued only if at least one of the following operands is 
omitted from the INTRO macro: STARTUP=, KEYLEN=, LNUNITS=, and (if 
DISK=YES is coded in INTRO) CPB=. If these operands are all coded in the 
INTRO macro, no WTOR message is issued at execution time. 

If the WTOR message IED002 is displayed, its first appearance is preceded by 
another message: 

IED001I TCAM JOB job name, stepname, procstepname 
ADDRESS OF AVT xxxxxxxx. 

This AVT address may be used by the operator to display (or modify, according to 
the system programmer's instructions) areas of the Message Control Program 
during the WAIT for the WTOR reply. 

After the TCAM system issues the WTOR message, it waits for a user response to 
be entered at the system console. The user has two options in responding: he 
may either enter response keywords (as shown in the '^response keyword" line in 
the list of INTRO operands), or he may enter INTRO operand names (as shown 
in the header Hne in the Hst of operands) together with appropriate values. Sev- 
eral keywords or operands, separated by commas or vertical bars ( | ) may be 
coded in one response. Responses may be entered in upper- or lowercase letters. 
They will be translated into uppercase automatically. Each response is Umited to 
41 characters. After a response has been entered, TCAM re-issues the WTOR 
message and continues to issue it after each response is entered until the user 
indicates, by coding U at the end of a response, that he has nothing more to 
specify. If the user codes U and has not yet specified values for STARTUP=, 
KEYLEN=, LNUNITS=, or (if DISK=YES is specified in INTRO) CPB= either 
in the INTRO macro or in a response to the WTOR message, TCAM prompts him 
with the following message: 

nn IED004A REQUIRED PARAMETER MISSING . SPECIFY operand 

where operand is the name of the missing INTRO operand. 

An error in specifying a response keyword or operand (such as an invaUd response 
keyword, an invaUd operand, or an invalid value with a response keyword) causes 
an error message to be printed at the console. The operator may respecify the 
response keyword or operand when he receives such a message. An error in one 
response keyword or operand prevents interpretation of any keywords in the same 
response to the right of the keyword in error. A response keyword or operand 
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may be coded more than once in the sequence of WTOR responses; the last value 
specified applies. 

Example: 

The following WTOR messages and responses occur at INTRO execution time for 
a user who has omitted the STARTUP= and LNUNITS= operands from his 
INTRO macro. The user specifies LNUNITS=, MSMIN=, MSMAX=, 
CPRCDS=, and CONTROL=, but forgets to specify STARTUP= (a required 
operand) and is prompted for this operand. 

message: 00 IED002A SPECIFY TCAM PARAMETERS 

response: r 00, ' B=2,MsMIN=80 X=95,E=5' 

message: 00 IED002A SPECIFY TCAM PARAMETERS 

response: r 00 , ' CONTROL=OPcONT, u ' 

message: 00 IED004A REQUIRED PARAMETER' MISSING . SPECIFY STARTUP^ 

response: 00 , ' s=c , u ' 

Note: // no response keyword is shown for a particular operand, the value 
for that operand may not be specified at INTRO execution time. 

INTRO has the following format: 



Name 


Operation 


Operands 


[symbol] 


INTRO 


keyword operands 



^ symbol 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



keyword operands 



PROGID=characters 



i 



Function: Specifies the operands that can be used. 

Format: The operands may be specified in any order according to assembler 

language conventions. 

Notes: The operands for the INTRO macro are described in the following Ust. 

This list also shows the one-character response keywords that may be substituted 

for the operand names in responses to the WTOR message SPECIFY TCAM 

PARAMETERS sent to the system master console at INTRO execution time. 



Response Keyword: None. 

Function: Specifies the name of the Message Control Program. 

Default: None. Specification optional. 

Format: One to 230 unframed characters with no embedded blanks or commas. 

Notes: TCAM inserts this name in a DC C* characters ' field located in the MCP. 

In a dump, this name appears in the EBCDIC field at the right of each page of the 

listing and identifies the beginning of executable code for the MCP. If this 

operand is omitted, no name is assigned to the MCP. 
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DISK= /no I 
|YESr 



Response Keyword: None. 

Function: Specifies whether any of the message queues data sets defined for this 

MCP are located on a direct-access secondary storage device. 

Default: DISK=YES 

Format: YES or NO. 

Notes: DISK = YES is coded if any of the message queues data sets are located on 

disk. DISK=NO is coded if no message queues data sets are located on disk. For 

further information, see Message Queues Data Sets in the chapter Defining 

Data Sets. 



V- 



CPB= C integer I 



Response Keyword: D= 

Function: Specifies the number of channel program blocks to be provided for 

transferring data between buffer units and message queues maintained on disk. 

Default: CPB=0 

Format: Unframed decimal integer. 

Maxim um: 65535 

Notes: One CPB is involved in transferring the data from one unit to disk, or in 

filling one unit with data from disk. See Specification of Channel Program 

Blocks in the chapter Defining Data Sets . 

If DISK=NO is coded, this operand is ignored by INTRO, and both CPB= and 
D= are invaUd responses at INTRO execution time. 



CIB= r integer) 

Response Keyword: C = 

Function: Specifies the maximum number of command input blocks (ICBs) that 
can be utilized at any one time in the TCAM system. 
Default: CIB=2 

Format: Unframed decimal integer. 
Maximum: 255 

Notes: CIBs are buffer-like areas used to contain operator commands entered at 
the system console. Space for them is allocated dynamically when needed, and the 
main-storage space assigned to a CIB. is freed once the operator command con- 
tained within the CIB has been processed. Only one CIB need be specified for 
operator commands entered from the system console. However, more than one 
CIB should be specified if the user anticipates processing simultaneously more 
than one operator command entered from the console. If an attempt is made to 
enter an operator command from the system console when the maximum number 
of CIBs are present already in the system (because that many operator commands 
from the system console are now being processed), the message being entered is 
rejected by TCAM. 

COIVllVIBUF=(integerl, integer!, integer3) 

Response Keyword: None. 

Function: Specifies the number of concurrent broadcast requests, the number of 

common data areas, and the size of each data area for 3670 terminals that receive 

broadcast messages. 

Default: None. Specification optional. 
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Format: Unframed decimal integer greater than zero. 
Maximum: 65535 for each integer. 

Notes: integer 1 specifies the total number of concurrent broadcast requests. This 
number should equal the maximum number of lines that could concurrently have 
outstanding COMMBUF requests, multipUed by the number of unfulfilled 
COMMBUF requests permitted on a line (see the COMMBUF macro descrip- 
tion), integer! specifies the total number of data areas to be generated, integers 
specifies the size of each data area; the data area size must include a 6 byte work 
area required at the COMMBUF macro and must be a multiple of four. In the 
inheader or inbuffer subgroups, the COMMBUF macro should be issued naming a 
TLIST macro and specifying the maximum number of broadcast operations that 
may be scheduled on a line at any given time. 



PRIMARY= rtermname^ 
{ SYSCON } 



Response Keyword: P= 

Function: Specifies the name of the station or application program to be used as 
the primary operator control station. 
Default: PRIM ARY= SYSCON 

Format: termname or SYSCON. termname is the name of a station or applica- 
tion program (defined by a TERMINAL or TPROCESS macro). If a station 
name is specified, the station not be on a switched line, and it must be able to 
enter and to accept messages. 

Notes: SYSCON is the name of the system console. The functions of the primary 
operator control station are given in The Operator Control Facility section of 
Using TCAM Service Facilities. 



If termname is changed by a CPRIOPCL operator command, execution of a warm 
or continuation restart causes the value that was specified in the macro to be 
overridden by the value specified by the last CPRIOPCL command executed 
before closedown or failure. 



CONTROL= (characters I 



Response Keyword: L= 

Function: Specifies the character string used to identify each operator command 

as such to TCAM. 

Default: CONTROL=0 

Format: One to eight unframed characters with no embedded commas or blanks. 

Notes: CONTROL=0 indicates that no character string is being specified; it is 

valid only if all operator commands are to be entered at the system console. 



KEYLEN=integer 



\ 



Response Keyword: K= 

Function: Specifies the size of a buffer unit. 

Default: None. This operand is required. 

Format: An unframed decimal integer greater than 34. 

Maximum: 255 

Notes: GuideUnes for coding this operand are given in the chapter Defining 

Buffers . This chapter should be thoroughly understood before KEYLEN= is 

specified. If disk queuing is used, integer must be identical to unitsize as specified 

in the DCB=(KEYLEN=unitsize) parameter of the lEDQDATA DD statement 

for the lEDQXA utility program used to preformat the disk queues. 
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UNITSZ=integer 



LNUNITS=mteger 



1VISUNITS= 



{» 



integer 1 



A buffer must be large enough to accommodate the larger of: 

a. a header prefix (30 bytes) plus the maximum number of reserve characters 
specified for the first buffer by the RESERVE = operand of any line group 
DCB macro or PCB macro, plus three bytes, or 

b. a text prefix (23 bytes) plus the maximum number of reserve bytes specified for 
buffers other than the first by the RESERVE= operand of any line group DCB 
macro or PCB macro, plus three bytes. 



Response Keyword: K= 

Function: Specifies the size of a buffer unit. 

Default: None. If KEYLEN= is specified, this operand must be omitted. If 

KEYLEN= is not specified, this operand is required. 

Format: An unframed decimal integer greater than 34. 

Maximum: 255 

Notes: This operand is an alternate spelling of the KEYLEN= operand. Either 

form, but not both, may be specified. 



Response Keyword: B= 

Function: Specifies the number of buffer units that may be used in building 

buffers to contain incoming and outgoing message segments. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than zero. 

Maximum: 65535 

Notes: Guidelines for coding this operand are given in the chapter Defining 

Buffers. 



Response Keyword: M= 

Function: Specifies the maximum number of buffer units that may be assigned to 
the main-storage message queues data set at any one time. 
Default: MSUNITS=0 
Format: Unframed decimal integer. 
Maxim um : 65535 

Notes: Guidelines for coding this operand are given in the discussion of main- 
storage message queues data sets in the chapter Defining the MCP Data Sets . 

This value is added to that specified for LNUNITS= to determine the total 
number of units in the buffer-unit pool. 

If MSUNITS=0 is specified or assumed, the expression M= may not be entered in 
the WTOR response at INTRO execution time. Therefore, if a main-storage 
message queues data set is desired, MSUNITS= must be coded with a nonzero 
integer, even if the value specified is to be overridden at INTRO execution time 
by an M= expression. 

Either MSUNITS= must be nonzero or DISK= YES must be coded. 



( 
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IVISIV1AX= 



( integer ^ 



!V1SIVIIN= { integer 1 

{5« I 



DLQ 



= I entry I 

\5 i 



> 



Response Keyword: X= 

Function: Specifies the percentage of the number of units (specified by the 

MSUNITS= operand) to be enqueued on a main-storage message queues data set 

before a warning is provided that the data set is nearly full. 

Default: MSMAX=70 

Format: An unframed decimal integer greater than zero. 

Maximum: 100 

Notes: When this percentage of units is enqueued, bit 6 is set in each message 

error record in the system. This operand is discussed in greater detail in the 

section on main-storage message queues data sets in the chapter Defining the 

MCP Data Sets. 



Response Keyword: Y= 

Function: Specifies the percentage of the number of units enqueued on a message 

queues data set (specified by the MSUNITS= operand) below which a bit is set in 

every message error record in the system. 

Default: MSMIN=50 

Format: An unframed decimal integer. 

Maximum: 99 

Notes: The operand may be used to inform the user that his message queues data 

set is no longer crowded. The value specified for MSMIN= must be less than that 

specified for MSMAX=, otherwise, the INTRO macro does not execute. Values 

specified for MSMIN= (or MSMAX=) at INTRO execution time by means of a 

WTOR response are checked against the current value of MSMAX= (or 

MSMIN=) if specified, to ensure that this rule is not broken. If the rule is broken, 

the value specified in the WTOR response is rejected and an error message is sent 

to the system master console informing the operator of this fact. The operator 

may then respecify the value. As an example, if MSMIN=95 and MSMAX=99 

are coded in the INTRO macro, at INTRO execution time the user should not 

code 

00 , ' MSMAX=90 , MSMIN=85 ' 

as a WTOR response, because the WTOR response is read from left to right and 
the new MSMAX value will be compared with the old MSMIN value and be 
rejected. If however, the user codes 

00, 'MSMIN=85,MSMAX=90' 

these values will be accepted since the new MSMIN value is less than the old 
MSMAX value, and the new MSMAX value is greater than the new MSMIN 
value, with which it is compared. 



Response Keyword: Q= 

Function: Specifies the name of the dead-letter queue to which messages with 

invalid destinations are sent. 

Default: DLQ=0 
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Format: entry is the name of a station or application program as defined by a 
TERMINAL or TPROCESS macro. DLQ=0 specifies that no dead-letter queue 
is to be used. 

Notes: Dead-letter messages are messages having invalid destinations as deter- 
mined by a FORWARD macro. If a user-specified routine is coded for the 
EXIT= operand of the FORWARD macro, messages with invahd destinations 
may have the destination corrected. If both the DLQ= operand of INTRO and 
the EXIT= operand of FORWARD are omitted, dead-letter messages are overlaid 
and lost. 



USEREG* (integer) 



Response Keyword: None. 

Function: Specifies the number of registers to be saved when in-line user code is 

located in an inheader or outheader subgroup that may handle multiple-buffer 

headers. 

Default: USEREG=0 

Format: An unframed decimal integer. 

Maximum: 10 

Notes: For guidelines on specifying this operand, see the section User Code in 

a Message Handler. USEREG= specifies sequential registers, beginning with 

register 2. For instance, if USEREG=4 is coded, registers 2, 3, 4, and 5 are 

saved. 



INTVAL= 



i integer^ 



Response Keyword: 1= 

Function: Specifies the number of seconds in the system interval. 

Default: INTVAL=0 

Format: An unframed decimal integer. 

Maxim um : 65535 

Note's: The system interval is described in Maintaining Orderly Message Flow in 

the chapter Defining Terminal and Line Control Areas . 



Unless a nonzero integer is specified either in the operand or in the response to a 
WTOR message at INTRO execution time, no system interval is possible for the 
MCP. 



CPINTVL- (integer 1 
^ 1800 I 



Response Keyword: V= 

Function: Specifies the maximum number of seconds between environment 

checkpoints when the TCAM checkpoint/restart facility is used. 

Default: CPINTVL=1800 

Format: An unframed decimal integer greater than 29. 

Maximum: 65535 

Notes: See the section TCAM Checkpoint /Restart Facility of the chapter 

TCAM Service Facilities for further information on this operand. 



( 
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CPRCDS= 



( integer ^ 



Response Keyword: E= 

Function: Specifies the number of environment checkpoint records to be retained 
in the checkpoint data set at any one time. 
Default: CPRCDS=2 

Format: An unframed decimal integer greater than 1. 
Maximum: 75 

Notes: The most recent records are the ones retained. For example, if 
CPRCDS=2 is specified, the most recent two environment checkpoints are kept in 
the checkpoint data set. When a new environment checkpoint is taken, its record 
overlays the oldest environment checkpoint record then being held in the data set. 
If an attempt is made to increase or decrease integer during a warm or continua- 
tion restart, the smaller value prevails. Guidelines for coding this operand are 
included in the discussion of the TCAM checkpoint/restart facihty in the chapter 
Using TCAM Service Facilities. 




Response Keyword: S= 

Function: Specifies the type of start-up to be performed following closedown of 

the Message Control Program or system failure. 

Default: None. This operand is required. 

Format: C, CI, CY, CYI, W, WI, WY, or WYI. 

Notes: The types of restart are defined in the discussion of the TCAM 

checkpoint/restart facility in the chapter Using TCAM Service Facilities . 

The values may be specified in any order. For instance, IC is just as valid and 
produces the same results as CI. 

C specifies that a cold restart is to be performed following a normal quick close or 
flush close, and that continuation restart (including scanning of the message 
queues) is to be performed following system failure. 

CY specifies that a cold restart is to be performed following a quick close, a flush 
close, or a system failure. 

W specifies that a warm restart is to be performed following a normal quick close 
or flush close, and that a continuation restart is to be performed following system 
failure. The continuation restart will include full scanning of the message queues. 



WY specifies that a warm restart is to be performed following a quick or flush 
close, and that a continuation restart is to be performed following system failure. 
The continuation restart will not include scanning of the message queues. I 
specifies that the status of each invitation list is to be included in the checkpoint 
record. If I is not coded, invitation Usts are not checkpointed. The status infor- 
mation recorded is as follows: 

1. whether the Ust is active or inactive, 

2. whether the Ust is autopoUed or program polled. 

The specification of I prevails from one cold restart to the next. Attempts to 
change this specification during a warm or continuation restart are ignored. 
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CKREQS= 



{integer "i 
5 / 



Response Keyword: R= 

Function: Specifies the maximum number of destination queues in use at any 

time for application programs that include a CKREQ macro. 

Default: CKREQS=0 

Format: An unframed decimal integer. 

Maximum: 255 

Notes: This operand specifies the number of checkpoint request records to be set 

up in a checkpoint data set. 



If an attempt is made to increase or to decrease integer during a warm or continu- 
ation restart, the smaller value prevails. 



RESTART= 



: { integer ) 

V- ] 



Response Keyword: N= 

Function: Specifies which environment checkpoint record the TCAM restart 

facility should use in attempting to reconstruct the MCP environment as it existed 

at the time of closedown or failure. 

Default: RESTART=0 

Format: An unframed decimal integer. 

Maximum: 255 

Notes: For more information on the use of this operand, see the section discussing 

the checkpoint/restart facility in the chapter Using TCAM Service Facilities . 



If is specified, the latest environment checkpoint record is used; if 1 is specified, 
the next to the latest record is used, etc. 



Although the maximum that may be specified is 255, the value entered must be 
less than the number of environment checkpoint records kept, as specified by the 
CPRCDS= operand. A scan is performed at restart if scanning is specified in the 
STARTUP = operand. If RESTART =0 is specified, or the operand is omitted and 
the latest environment checkpoint record cannot be used (due, perhaps, to a disk 
I/O error), TCAM automatically goes back to the latest usable record and uses it. 

If the message queues data set is on reusable disk and the integer specified causes 
TCAM to attempt to restructure the environment from a checkpoint record that 
was taken before serviced messages in certain queues were overlaid, it is unlikely 
that a warm restart or a continuation restart will be successful. 

This value should not be changed during a warm or continuation restart. 



PASSWRD= r characters \ 



Response Keyword: W= 

Function: Specifies a character string that must be entered in an MRELEASE, 

MCPCLOSE, TCHNG, or ICHNG macro issued in an application program. 

Default: PASSWRD=0 

Format: One to eight unframed characters with no embedded blanks or commas. 

Notes: If this operand is coded, none of the above macros are executed unless 

they have the correct password. A macro with an incorrect password or no 

password is ignored. PASSWRD=0 indicates that no password is being specified. 



( 
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The user will be unable to find the password as specified here in a storage dump; 
an internal TCAM routine scrambles the password at INTRO execution time. 



CROSSRF= r integer I 

I? I 



Response Keyword: F= 

Function: Specifies the number of entries in the cross-reference table. 

Default: CROSSRF=0 

Format: An unframed decimal integer. 

Maximum : 65535 

Notes: The cross-reference table is a debugging aid. Each entry contains either a 

name or an address of an internal TCAM control block associated with a line. If a 

cross-reference table is to be used, CROSSRF= should specify the maximum 

number of TCAM lines that are open simultaneously. 



This facility is described in the Debugging Aids section of the chapter Using 
TCAM Service Facilities. 



TRACE= r integer) 



Response Keyword: T= 

Function: Specifies the number of entries in the TCAM input/output trace table. 

Default: TRACE=0 

Format: An unframed decimal integer. 

Maximum : 65535 

Notes: This table provides a sequential record of the I/O interruptions occurring 

on a specified line and is described in greater detail in Debugging Aids in the 

chapter Using TCAM Service Facilities. 



TREXlT=symboI 



Response Keyword: None. 

Function: Specifies the entry point of a user- written routine to be given control 

when all entries in the TCAM I/O trace table have been used. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 
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Notes: The routine is passed the address of the I/O trace table in register 0. 
Nothing is returned by the routine. There is no special restriction on what may be 
done with the table in the routine (that is, the information might be transferred to 
an external device such as the printer). The COMWRITE feature can also be 
used to provide a copy of the I/O trace table. This operand cannot be specified if 
TRACE=0. 

The entries are reusable and may be updated while the exit routine is processing 
them, since they are updated by code that is disabled to interrupts. 



DTRACE= J integer 



Response Keyword: A= 

Function: Specifies the number of entries in the TCAM dispatcher trace table. 

Default: DTRACE=0 

Format: An unframed decimal integer. 

Maxim um : 65535 

Notes: The dispatcher trace table is a debugging aid that keeps a sequential record 

of subtasks activated by the TCAM dispatcher. This table is disscussed in Using 

TCAM Service Facilities . One entry is created for each subtask activated; when 

the end of the table is reached, the table is wrapped and new entries overlay the 

oldest entries. 



OLTEST= (integer) 

112 / 



Response Keyword: 0= 

Function: Specifies the number of 1024-byte blocks of main storage to be used 

for on-line test procedures. 

Default: OLTEST=12 

Format: The unframed decimal integer 0, or an unframed decimal integer greater 

than 11. 

Maximum: 255 

Notes: For information on coding this operand, see On-Line Test Function iti the 

chapter Using TCAM Service Facilities . If the on-line test capability is not 

needed, OLTEST=0 should be coded. If the operand is omitted, 12K of main 

storage is reserved for OLT. 



/I 

1 



COMWRTE= (yes) 



Response Keyword: G= 

Function: Specifies that COMWRITE (Service Aid Writer Task) is to be at- 
tached to the TCAM MCP. 
Default: COMWRTE=NO 
Format: YES or NO. 

Notes: If COMWRTE=YES is specified, a COMWRITE DD card describing a 
sequential data set must be included in the job control cards for the execution of 
the TCAM MCP. Omission of the DD card causes abnormal termination of 
COMWRITE, and the COMWRITE function is not available. Other than the loss 
of the function, the TCAM MCP is not affected. 



( 
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WTTONE= j integer^ 

\5 J 



Response Keyword: None. 

Function: Specifies the duration of the "mark" character for the World Trade users 

whose BSC lines require a "line tone." 

Default: WTTONE=0 

Format: An unframed decimal integer. 

Maximum: 450 

Notes: Restricted to use in World Trade countries. This operand specifies the 

number of characters that constitute the tone. 



TOPlV1SG= 



^YES j 



Response Keyword: H= 

Function: Specifies whether the operator awareness message lEAOOOl is to be 

displayed at the primary operator control station when a polled station fails to 

respond to polling. 

Default: TOPMSG=YES 

Notes: The message is described in the section TCAM I/O Error-Recording 

Facilities in the chapter Using TCAM Service Facilities . 



LINETYP= / BISC 
) STSP 
\ MINI 
V BOTH 



If YES is specified, the message is displayed each time a station fails to respond to 
polling during a pass through the invitation Ust (because, for instance, the station 
is inoperative). 



Response Keyword: None. 

Function: Specifies the type of Unes used in the TCAM system. 

Default: LINETYP=BOTH 

Format: BISC, STSP, MINI, or BOTH. 

Notes: BISC is specified if all Unes in the system are BSC lines only. STSP is 

specified if all Hnes are start-stop only. MINI is specified if all lines in the system 

are IBM 1050 terminals on leased lines. BOTH is specified if all types of lines are 

supported. 



FEATURE=( (NODIALK 
i DIAL ) 



( N02741 
/2741 



(• 



JNOTIMERM 
I TIMER S 



Response Keyword: None. 

Function: Specifies additional features to be supported in the TCAM system. 

Default: FEATURE=(DIAL,2741, TIMER) 

Format: NODIAL or DIAL, N02741 or 2741, and NOTIMER or TIMER. 

Framing parentheses must be coded. If a suboperand other than the last is 

omitted due to default, a comma must be coded to indicate that it is missing. 

Notes: DIAL is specified if dial lines are used. If 2741 terminals are supported, 

2741 should be coded. The TIMER suboperand should be specified if any of the 

following features are included in the system: 
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checkpoint 
any interval 
dial-out options 
main-storage queuing 
reusable disk queuing. 

If NOTIMER is specified but a function requiring the timer is used, TCAM 
terminates abnormally with a system ABEND code of 045 and a value of 06 in 
register 15. 

Note: Following the INTRO macro the user should include a section of code 
that tests the return code in register 15 to determine whether INTRO has 
executed correctly. If register 15 contains anything other than zero after 
execution of INTRO, it is unlikely that the MCP will work satisfactorily. 
(See the sample activation and deactivation section of the MCP at the end of 
this chapter for a section of user code that checks the INTRO return code 
and branches to an ABEND macro if the return code is anything other than 
zero.) 

If a nonzero code is to be returned by the INTRO routine, TCAM displays the 
message 

IED065I TCAM INITIALIZATION ERROR xxxx 

v/here xxxx is the decimal equivalent of the value returned in register 15; the 
values that may be returned are: 

Code Meaning 

4 TCAM is already in the system. 

8 There is insufficient main storage for generating one of the following: 

a. buffer-unit pool— refer to the LNUNITS= and MSUNITS= oper- 
ands. 

b. CPB free pool — refer to the CPB= operand. 

c. subtask trace table — refer to the DTK ACE = operand. 

d. line I/O trace table — refer to the TRACE= operand. 

e. cross-reference table — refer to the CROSSRF= operand. 

12 There is insufficient main storage for generating a temporary work table 

used by TCAM to sort the termname table (see the TCAM PLM for a 

discussion of the termname table). 
16 Terminal definition error. An invalid value was specified on the 

ALTDEST= operand of either the TERMINAL or the TPROCESS 

macro. 
20 The primary operator control station is invalid. Either no such terminal 

entry exists, or SECTERM=YES is not specified for the terminal named 

on the PRIMARY = operand of the INTRO macro. 



{ 
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I 



OPEN 



The OPEN macro 

• completes initialization and activation of data sets belonging to the Message 
Control Program; 

• is required for each MCP data set represented by a DCB macro; and for log 
data sets (if present), 

• specifies whether activation of lines represented by line group data sets is to be 
immediate or deferred. 

OPEN is used to complete initialization and activation of MCP data sets, and to 
provide an interface with the BSAM routines handling the logging function for 
TCAM. Each MCP data set required for execution (with the exception of a 
message queues data set in main storage) must be activated in the Message 
Control Program by an OPEN macro. Log data sets, if present, are also activated 
by an OPEN macro issued in the MCP. Each MCP data set may be activated by a 
separate OPEN macro, or all data sets of the same type (for example, all line 
group data sets, or all message queues data sets) may be activated as a group by a 
single OPEN. If message queues data sets residing on disk are present, they must 
be opened first. The checkpoint data set, if present, must be opened next. 

Instead of a standard OPEN macro, the user may code a list and an execute form 
of the macro, which would be used in conjunction with each other; for general 
information on the Ust and the execute form of a macro, including a discussion of 
the advantages of using these forms, see the OS publication Supervisor Services . 

When an OPEN macro tries and fails to properly open a TCAM data set, an error 
message is sent to the system console. This error message, which specifies the 
data set that could not be satisfactorily opened and tells why it could not be 
opened, is described in the section User ABEND Exits of the chapter Defining 
the MCP Data Sets . In addition to sending the error message, TCAM allows the 
us.er to specify a user-written subroutine that receives control when an OPEN 
macro fails to execute properly. This capabiUty is described in the User ABEND 
Exits section. If the user fails to provide this subroutine, TCAM issues an 
ABEND macro for the MCP program when an OPEN fails to execute properly. 

When an OPEN macro is executed for a Hne group data set, TCAM issues com- 
mands to prepare each line for message traffic. If TCAM does not receive an 
indication that the commands have successfully executed within 28 seconds from 
the time they were issued, the line is considered to be temporarily unavailable, and 
the following message is written at the system console: 

IED079I ENDING STATUS NOT RECEIVED FROM 
LINE nnn — LINE UNAVAILABLE 

The unavailable line may subsequently be started by the STARTLINE operator 
command. Unavailability of one Une does not affect preparation for message 
traffic over other lines in the line group. 

The operand field of the OPEN macro consists of one or more groups of position- 
al operands, followed by a single keyword operand. Each group of positional 
operands consists of the name of the data control block for the data set being 
opened (the name of the block is the same as the name of the DCB macro that 
created it) and some optional information about that data set. A comma is coded 
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between groups. The optional keyword operand at the end permits the list and the 
execute form of the macro to be specified. 



OPEN has the following format: 



Name 


Operation 


Operands 


[symbol] 


OPEN 


(dcbname,[((OUTPUT)[,IDLE])],...) 
{ INOUT > 
1 INPUT ) 

Umf=l n 

\MF=(E,listname) j 



symbol 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Notes: If MF=L is specified, this macro name must also be provided. It becomes 

the name of the parameter list generated by the macro. 



dcbname 



Function: Specifies the name of a data control block identical with the name 

specified in the symbol field of the DCB macro for the data set being opened. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: Register notation may also be used, in which case the specified register (2 

through 12) should contain the address of the data control block for the data set 

being opened. 



,4 



> OUTPUT I 
' INOUT 
I INPUT ' 



Function: Specifies the type of data set with respect to the direction in which 

message traffic may flow. 

Default: INPUT 

Format: OUTPUT, INOUT, or INPUT. 

Notes: OUTPUT specifies an output data set; it must be specified for a log data 

set. The operand may be coded for a line group data set if none of the lines are to 

stations that can enter data; in this case, the INVLIST= operand of the Hne group 

DCB macro must refer to an invitation list having no entries (see the description 

of the INVLIST macro). 

INOUT specifies a data set that can be used for both input and output. INOUT 
must be specified for a DASD message queues data set or a checkpoint data set, 
and should be specified for a line group data set if any of the lines are to stations 
that both enter and accept data. INPUT specifies an input data set. This operand 
may be specified if none of the lines are to stations that can accept data. 



( 
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IDLE 



IMF 



=^L 
<(E,H 



Hstname) 



> 



Function: Specifies whether the lines are to be activated when OPEN is executed. 
Default: None. Specification optional. 
Format: IDLE 

Notes: This operand is meaningful only for a line group data set. If IDLE is 
coded, the line group data set is initialized at OPEN execution time, but the lines 
are not activated. That is, no invitation or selection is performed for stations on 
this line. Such Unes may be activated individually by a STARTLINE operator 
command. If IDLE is omitted, all lines in the line group are automatically activat- 
ed when the OPEN macro is executed. For nonswitched lines to stations having 
polling characters, poUing of stations having active entries in the invitation lists for 
the lines begins after OPEN is executed, provided that INPUT or INOUT is also 
specified. 

A station assigned to a switched Une that is idle may not call in on that hne, but 
may call in on any active Une in its line group to enter messages. Such a station 
will not receive any messages queued for it until the line it is on is activated by the 
STARTLINE operator command. 

If neither INOUT, INPUT, OUTPUT, nor IDLE is specified for a particular data 
set, and a subsequent data control block address is specified in the sublist, two 
commas must appear between the two specified data control block names. 



Function: Specifies whether the OPEN macro is to generate a parameter Ust only 
or is to generate executable code. 
Default: None. Specification optional. 

Format: Hstname specifies the name of an OPEN macro specifying MF=L. 
Notes: MF=L causes creation of a parameter list based on the OPEN operands. 
No executable code is generated. The user must specify this form of the OPEN 
among his program constants. The parameters in the Ust are not used until the 
program issues an OPEN or CLOSE macro with an MF=(E,Ustname) operand 
that refers to the Ust. The name specified in the name field of the OPEN macro 
becomes the name assigned to the parameter Ust. MF=(E,listname) causes 
execution of the OPEN routine using the macro having the MF=L operand 
specified. Parameters specified through a macro having MF=(E,Ustname) operand 
override corresponding parameters in the list. 

Example: 

The following OPEN macros open: 

L Two DASD message queues data sets named (as assigned by their DCB mac- 
ros) DISKREUS and DISKNON; 

2. A checkpoint data set named TPCHK; 

3. A line group data set named GROUPONE, and another line group data set 
named GROUPTWO that is to be opened idle; 

4. A log data set named MSGLOG. 

OPENDISK OPEN ( DISKREUS , ( INOUT ) , DISKNON , ( INOUT ) ) 

OPENCKPT OPEN ( TPCHK, ( INOUT ) ) 

OPENLINE OPEN ( GROUPONE , ( INOUT ) , GROUPTWO , ( INOUT , IDLE ) ) 

OPENLOG OPEN ( MSGLOG , ( OUTPUT ) ) 

Note that the message queues data sets are opened first and that the checkpoint 
data set is opened next. 
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READY 



The READY macro 

• completes initialization and activation of the MCP; 

• permits ''Good Morning" and "Restart in Progress" messages to be specified; 

• must be issued between the OPEN macros and the CLOSE macros in the 
activation and deactivation section of the MCP. 

The READY macro completes initialization and activation of the Message Control 
Program; once READY has executed, the TCAM system is prepared for message 
traffic. One READY macro is specified per MCP, and is located between the 
OPEN macros and the CLOSE macros in the activation and deactivation section 
of the MCP. 

Two optional operands of READY provide the addresses of user-written routines 
that may build "Good Morning" or "Restart in Progress" messages or that might 
alter option fields and other control areas to reflect the fact that a restart has 
occurred. The exit for the "Good Morning" message is taken for the initial 
start-up of the MCP and for each cold restart; the exit for the "Restart in 
Progress" message is taken for a warm or a continuation restart (for a discussion 
of the various types of TCAM start-up, see TCAM Checkpoint /Restart Facility 
in Using TCAM Service Facilities ). 

When initial start-up or a restart occurs, the appropriate routine is given control 
for each station defined by a TERMINAL macro, provided that the line group 
data set containing the line on which the station is located has been opened by an 
OPEN macro. The user routine should save and restore registers. When control 
passes to the user routine, register 1 contains the address of a two-word parameter 
list. The first word in the Ust contains the address of the terminal table entry for 
the station to which the message generated by the user is to be sent; the second 
word contains the address of the option fields for the destination station. The user 
routine may use this information to build a message tailored to this particular 
station, and may also alter fields in the terminal table entry and the option fields 
for the station to reflect the fact that a restart has occurred (for a warm start or 
continuation restart, the data in the terminal table entries and the contents of the 
option fields before closedown or failure are preserved by the checkpoint faciUty). 

The user routine returns to the MCP, in register 15, the address of a message to be 
sent to the station. An all-zero address indicates that no message is to be sent to 
this station. At the specified address is a one-byte field indicating, in binary form, 
one more than the number of bytes of data in the message, followed by the text of 
the message. The maximum length of the message is 255 bytes. If queuing is by 
terminal, TCAM places the message at the head of the queue for the destination 
station so that it is the first message sent to that station following start-up or 
restart. The message is handled by the outgoing group of the Message Handler for 
the destination, and is transmitted like any other message. Since the message is 
handled by an MH group, it must have a header similar in format to the headers of 
messages usually handled by the group. The user must construct this header in his 
exit routine and include it as the first part of his message. 

If queuing is by line, the good morning or restart messages for the stations on a 
line will be placed at the head of the destination queue for that Hne, and will be 
sent before any other messages on that queue. 



( 
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READY has the following format: 



symbol 



GMIVISG=routine 



RSIVlSG=routiiie 



Deactivation 



Name 


Operation 


Operands 


[symbol] 


READY 


[GMMSG=routine][,RSMSG=routine] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of a user- written, closed subroutine that builds 

good morning messages on each line. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is coded, the routine is given control at the initial start-up 

and at each cold restart. 



Function: Specifies the name of a user- writ ten, closed subroutine that builds 

restart messages. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is coded, the routine is given control at a warm restart or a 

continuation restart. 

The routines are coded and assembled as part of the MCP in the same manner as 
the Message Handlers. Their exact location is not important since they are called 
as closed subroutines. See User Code in a Message Handler in the chapter 
Designing the Message Handler for the correct linkages. 



Orderly deactivation of the TCAM system involves a number of steps. Incoming 
and outgoing message traffic must be stopped, and if the status of the system is to 
be preserved, a checkpoint record must be made. Data sets for any application 
program using TCAM be closed. Finally, the MCP data sets must be closed and 
control returned to the OS Supervisor. 



Types of Closedown 



Closedown of a TCAM system may be initiated either by a SYSCLOSE operator 
command or by an MCPCLOSE macro issued in an application program. These 
two means of initiating closedown are described in the next two sections. Both 
the operator command and the macro have an operand that specifies whether a 
flush closedown or a quick closedown is to be effected. A flush closedown may 
also be initiated internally when the nonreusable disk threshold is reached. 

A flush closedown is one in which incoming message traffic on each line ceases 
after the message being received at the time closedown is ordered has been 
completed (the line is not repoUed or re-enabled). As soon as incoming message 
traffic on each line ceases, any eligible outgoing messages that have been queued 
for stations on that line are sent. (An eligible message is a message to a station or 
application program that is not intercepted; see the description of the HOLD 
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macro.) In this manner, incoming message traffic declines to nothing, while 
outgoing message traffic continues until all ehgible messages have been sent. An 
environment checkpoint record is taken after all eligible outgoing messages have 
been sent. This record preserves the status of the MCP and also records the 
locations on disk of outgoing messages that could not be sent because their 
destinations were intercepted; after restart, these messages are sent once their 
destinations are eligible to receive them. This form of termination is known as a 
flush closedown because unsent messages are flushed from the message queues. 

When a quick closedown is ordered, message traffic stops on each line as soon as 
transmission of any message currently being sent or received on the line has been 
completed. Queues of messages to be sent are not flushed but their status is 
preserved by an environment checkpoint record, and they are sent to their appro- 
priate destinations after restart. (See the discussion of the TCAM 
checkpoint/restart facility in the chapter Using TCAM Service Facilities .) 

Deactivating a TCAM System without Application Programs 

If there are no appUcation programs in the TCAM system, a SYSCLOSE operator 
command entered at an operator control station deactivates the system. The 
SYSCLOSE command is discussed in the operator control section of the chapter 
Using TCAM Service Facilities. 

The SYSCLOSE command specifies either a quick or a flush closedown. When 
the command is executed, traffic is suspended on each Hne, as described above. 

When all message traffic and TCAM disk operations are complete, control returns 
to the first instruction following the READY macro in the Message Control 
Program. This instruction must begin a user-written routine (or branch to a 
routine) that deactivates the Message Control Program. This MCP deactivation 
routine must issue CLOSE macro instructions for each open data set in the 
Message Control Program. 

The last TCAM data sets to be closed must be the checkpoint and then the DASD 
message queues data sets. This is important, because closing these data sets 
deactivates the telecommunications system. After the message queues data sets 
have been closed, no further references can be made to queues, control blocks, the 
terminal table, invitation lists, etc. The deactivation routine should end with a 
RETURN macro to end the message control job. (For a sample MCP deactiva- 
tion routine, see the last section of this chapter.) 

Deactivating a TCAM System With Application Programs 

When the TCAM system includes apphcation programs, closedown may be 
effected by an MCPCLOSE macro issued as part of a termination routine in an 
application program. A recommended procedure is to enter a special closedown 
message at a station; this message would be directed to each active application 
program in the system (by specifying the names of the appropriate process entries 
in the terminal table as destinations). Each application program might contain a 
user-written termination routine that would be activated when the message was 
received. The termination routine might perform the following steps: 

1. Close any open application-program data sets; 

2. Issue an MCPCLOSE macro; 

3. Issue a system RETURN macro in order to end the apphcation program job. 

The user may code the SETEOF macro to execute on his closedown message. 
When the application program receives the message on which SETEOF has 
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executed, it branches to the address specified by the EODAD= operand of the 
input DCB macro when the next GET or CHECK macro is issued; at this address 
the user may have his closedown routine. 

When multiple application programs are being closed, an MCPCLOSE macro may 
be issued in each; the MCPCLOSE macro issued first is the only one to execute. 

The MCPCLOSE macro checks to see whether an MCPCLOSE macro has 
already been issued; if so, the macro does not execute, but places a return code of 
X'OO' in register 15. The first MCPCLOSE macro issued causes all message 
traffic on TCAM lines to cease, as described above in the discussion of the types 
of closedown. An operand of MCPCLOSE specifies either a quick or a flush 
closedown. After all message traffic has ceased, the Message Control Program 
checks for open application-program data sets; when all such data sets are closed, 
control passes to the instruction following the READY macro in the MCP. This 
instruction begins a user-written routine (or branches to a routine) that issues 
CLOSE macros for each data set opened in the MCP and ends with a system 
RETURN macro. A sample routine is given in the last section of this chapter. 

Instead of using an MCPCLOSE macro, the user may utilize the SYSCLOSE 
operator command to close a TCAM system having application programs. If any 
application program data sets are open at the time message traffic ceases, an error 
message is directed to the system console; the error message lists the open data 
sets for that application program. If more than one application program has open 
data sets, the message for the second application program will not be sent to the 
console until all data sets for the first program are closed. When these data sets 
are closed, the system is deactivated. 

i^ SYSCLOSE and MCPCLOSE will also allow the user to close all open application 

program DCBs by forcing the GET/READ routine to take the EODAD exit for 
each open input DCB. This is done only if the user codes the STOP= operand 
and the EODAD= operand on the input DCB. The error message is still issued 
because the user EODAD= operand may not point to a closed routine. 

Note: When issuing the READ macro without issuing the CHECK macro, 
at least one message must be read before the EODAD exit is taken. 



i 
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CLOSE 



symbol 



(dcbname,,...) 



The CLOSE macro 

• is issued in the Message Control Program to deactivate any log data set, line 
group data set, checkpoint data set, and DASD message queues data set that is 
open in the MCP; 

• must appear following the READY macro or be branched to from instructions 
following READY. 

CLOSE has the following format: 



Name 


Operation 


Operands 


[symbol] 


CLOSE 


(dcbname,,...) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the names of the data control blocks for the data sets being 
closed. 

Default: None. This operand is required. 

Format: Each dcbname must conform to the rules for assembler language sym- 
bols and must correspond to the name specified on the DCB macro for the data 
set being closed. 

Notes: Register notation may be used, in which case the addresses of the data 
control blocks must previously have been loaded into the general registers speci- 
fied. 

All MCP data sets of the same type (for example, all hne group data sets or all 
message queues data sets) can be closed with one CLOSE macro by including the 
names of their data control blocks as operands. If more than one dcbname is 
coded in a CLOSE macro, the names are separated by double commas. 

If present, the last TCAM data sets to be closed must be the checkpoint and then 
the DASD message queues data sets. 

Sample MCP Activation and Deactivation Section 

The code in Figure 8 represents an activation and deactivation section as it might 
appear in an MCP. The section consists of an INTRO macro, some user code that 
tests whether INTRO worked correctly and causes termination of the MCP if 
INTRO did not execute properly, OPEN macros, a READY macro, and CLOSE 
macros. The TCAM macros in this section should appear in the order shown. 



Since the CPB= operand of the INTRO macro is omitted (and DISK=YES is 
coded), the TCAM system will issue a WTOR message at INTRO execution time; 
in his response to this message, the user may specify a value for CPB= and 
override or supply values for many other INTRO operands. 



( 
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TCAMINIT INTRO PROGID=MCPONE , 
DISK=YES, 
CONTROL=OPID, 
KEYLEN=48, 
LNUNITS=20, 
DLQ=NYC, 
USEREG=10, 
CPINTVL=1000, 
STARTUP=W, 
CKREQS=2, 
PASSWRD=VALIDMSG , 
CROSSRF=10 
OLTEST=10 

LTR 15,15 

BZ OPENDISK 



4c 

NOEXEC 
* 

OPEN DISK 



ABEND 12 3, DUMP 

OPEN (DISKREUS,( INOUT ) , DISKNON, ( INOUT ) 
TM DISKREUS+48, 16 
BNO NOEXEC 



PROGRAM IDENTIFICATION 

USING DISK 

FOR OPERATOR COMMANDS 

UNIT LENGTH 

NUMBER OF UNITS 

DEAD-LETTER QUEUE 

REGISTERS TO BE SAVED 

CHECKPOINT INTERVAL 

WARM RESTART 

CHECKPOINT REQUESTS 

PASSWORD FOR APPLICATIONS 

CROSS-REFERENCE ENTRIES 

ON-LINE TESTS 

TEST IF INTRO WORKED 

IF SO OPEN DATA SETS 

IF NOT TERMINATE WITH DUMP 

OPEN DISK DATA SETS 
TEST IF OPENS WORKED 
NO-TERMINATE 



* 
* 
* 
* 

* 

* 
* 

* 



TM DISKNON-f48, 16 
BNO NOEXEC 



CPENCKPT OPEN ( TPCHK, ( INOUT ) ) 
TM TPCHK4-48,16 
BNO NOEXEC 



OPEN CHECKPOINT DATA SET 



OPENLINE OPEN ( GROUPONE , ( INOUT 

TM GROUPONE+48, 16 

BNO NOEXEC 

* 

TM GROUPTWO+48, 16 

BNO NOEXEC 



I , GROUPTWO , ( INOUT , IDLE ] 



OPEN LINES 



OPENLOG OPEN ( MSGLOG , ( OUTPUT : 

TM MSGLOG+48,16 
BNO NOEXEC 



OPEN MESSAGE LOGGING DATA 
SET 



ALLSWELL READY GMMSG=RTNA, RSMSG=RTNB 
* 

FINISHUP CLOSE ( GROUPONE ,, GROUPTWO ) 

CLOSE (MSGLOG) 

CLOSE (TPCHK) 

CLOSE ( DISKREUS , , DISKNON ) 

L 13,4(13) 
RETURN ( 1 4 , 1 2 ) , , T 



Figure 8. Sample MCP Activation and Deactivation Section 



BEGIN EXECUTION 

CLOSE LINE GROUP DATA SETS 

CLOSE LOG DATA SET 

CLOSE CHECKPOINT DATA SET 

CLOSE DISK DATA SETS 

PREPARE TO RETURN 

RETURN CONTROL TO OS 

SUPERVISOR 



The section of user code following the INTRO macro is optional, but the user 
should test the return code in register 15 to determine whether INTRO has 
executed correctly. If register 15 contains anything other than zero after execu- 
tion of INTRO, the chances are that the MCP will not work properly. 



I 



The OPEN macro in Figure 8 is the same as that used as an example in the 
previous section. The DASD message queues data sets are opened first, and the 
checkpoint data set is opened next. (Neither of these data sets is required, but if 
present they should be opened in the order shown.) 
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A user-written subroutine may be utilized to perform error checking and correc- 
tion when a TCAM data set fails to open. The EXLST= operand of the DCB 
macro for the data set may be coded so that control passes to the user's subroutine 
whenever the data set fails to open. (For more information on the EXLST= 
operand, see the descriptions of the DCB macros for the various TCAM data 
sets.) In this example, the flags set by the OPEN macro are tested for successful 
completion. Open flags are at an offset of 48 beyond each DCB macro and are set 
to 16 if the data set is opened correctly. If the open flags are not equal to 16, the 
abnormal exit is taken. 

The READY macro is the last macro of the activation section. RTNA is the name 
of a user-written, closed subroutine that will be activated for the initial start-up 
and each cold restart; RTNB is given control for warm and continuation restarts. 
Both routines are entered once for each station represented by an entry in the 
terminal table and located on a line whose Une group data set has been opened. 

The first CLOSE macro begins the deactivation section. This CLOSE will not be 
executed until all data sets in TCAM application programs have been closed down 
and until all lines have been closed to traffic by means of a SYSCLOSE operator 
command or an MCPCLOSE macro issued in an application program. The first 
CLOSE is given control by TCAM once Hne traffic has ceased. Notice that the 
DASD message queues data set is closed last, immediately after the checkpoint 
data set; this practice should be followed when these two data sets are present. 

The instructions following CLOSE return control to the OS Supervisor. 



i 
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Message Format 



Designing the Message Handler 



The heart of a Message Control Program consists of the Message Handlers , the 
sets of routines that operate upon messages being received from or sent to remote 
stations or appUcation programs. A Message Handler is defined by a sequence of 
TCAM macro instructions and is constructed to handle messages for a particular 
line group or for several line groups that have similar characteristics. 

A Message Handler (MH) defines macro-introduced routines that: 

1. Examine and process control information in message headers; 

2. Perform necessary functions in preparing message segments for forwarding to 
theirdestinations, which may be stations or application programs. 

There are two kinds of macro instructions that may be included in a Message 
Handler: functional and delimiter macro instructions. The functional macros 
perform the specific operations required for messages directed to the Message 
Handler. Delimiter macros classify and identify sequences of functional macro 
instructions and direct control to the appropriate sequence (some delimiter macros 
have limited functional capabilities). 

Designing a Message Handler consists of selecting certain TCAM macro instruc- 
tions described in this chapter and writing them in a particular sequence, accord- 
ing to the requirements of the application and the characteristics of the hnes. It is 
important to consider the type of station and the type of line in use, the processing 
requirements of different types of messages, and the format of the message 
headers to be handled. 

Before discussing the Message Handler and its parts, we shall briefly consider the 
format of the TCAM message and its message header. 



A message may consist of two parts, the header and text. The header contains 
control information for the message, such as: 

• one or more destination codes, 

• the code name for the originating station, 

• the number of the message relative to previous messages received from that 
station(input sequence number), 

• a message-type indicator, 

• various other fields containing control indicators. 

The text of a message consists of information of concern to the party ultimately 
receiving the message, either a station or an application program. 

Depending on the application, messages may consist of a header only, text only, or 
header and text. A header-only message may utilize a message-type indicator to 
route the message to an application program and, possibly, obtain a standard 
response. If all messages go to only one application program, such as a file-update 
program, the header may be omitted. 

The determination of what part of the message is the header and what part is text 
is up to the user. 

Depending on the type of work unit with which he is deaUng, the user must specify 
appropriate characters for control purposes. The types of work units are: 
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• A block is that portion of a message terminated by an EOB or ETB control 
character, or, if this is the last block in the message, by an ETX or EOT control 
character. A subblock is that portion of a BSC message terminated by an ITB. 

• A segment is that portion of a message contained in a single buffer. The size of 
the buffer is specified by the user for each line group and appUcation program. 

• A record for an application program is, most often, that portion of a message 
terminated by a format character (ESC, NL, TAB, CR, or LP), or a message 
portion terminated by a character specified by the data operand of the 
MSGEDIT macro (see the description of this macro). 

• A physical message is a unit of data terminated by an EOT or ETX control 
character, or, if the CONV= operand of the STARTMH macro is coded 
CONV= YES, by an ETB or EOB control character (see the description of the 
STARTMH macro). 

• A logical message is a unit of data defined by the user (see the description of 
the SETEOM functional macro). If the user does not define logical messages 
for his network, TCAM assumes that a logical message is equivalent to a 
physical message. 



The Message Header 



Operating on the fields of the message header is the primary function of Message 
Handlers in the Message Control Program. The length and format of the header 
and the information it contains depend solely on the requirements of the appUca- 
tion and the user's preferences. The length may be a few characters or many 
characters. A header may occupy more than one buffer. However, the entire 
header of a message must be contained within the first block of the message. 
EOBs may not be embedded within a header. 



The format of the message header dictates the arrangement of the appropriate 
Message Handler macros. The control characters used and the sequence of fields 
within the header must be predetermined so that the Message Control Program 
can be properly coded. 

Destination codes in the message header identify the stations or application 
programs to which the message is to be routed. The message-type indicator can 
identify a header that is to be processed in a special manner. By coding certain 
macro instructions, the user can insert in the header such data as the date and time 
it is sent, and the output sequence number. 

There are many possible variations for the format of a message header. The 
sample formats shown in Figures 9 and 10 are included simply for illustrative 
purposes. 

The format shown in Figure 9 could be used in a message switching appUcation. 
This figure shows how an incoming message might look just before it comes into 
main storage. 

In this example, the EBCDIC blank character (here denoted by the symbol b) 
serves as a delimiter for each header field. This is not always the case, however; 
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Figure 9. Sample Format for an Incoming Message 
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some MH macros operating on the header do not look for field delimiters, but 
consider a certain number of characters or a certain sequence of characters to be a 
header field. To determine what constitutes a header field for any particular 
macro, the user should consult the description of that macro in the section 
Functional Macro Instructions . 

Byte contains a machine end-of-address (EOA) character inserted by the 
station. When the message is transmitted, this character signals the end of ma- 
chine control characters (such as addressing characters and the machine EOA 
itself, which are not recorded) and the beginning of data characters. Depending 
upon how the LC= operand of the STARTMH macro of the Message Handler is 
coded, TCAM may remove the machine-control characters and the machine EOA 
before placing the message in main storage. The 192 in bytes 1 through 3 is the 
input sequence number. Bytes 5 through 7 contain the code for the terminal that 
originated the message. Bytes 9 through 11 and 13 through 15 contain destination 
codes specifying the stations to which the message is to be sent. In this example, 
the semicolon in byte 17 has been designated by the user as the program EOA 
character. Since some of the messages in this application contain multiple destina- 
tion codes, the destination delimiter character must follow the last destination 
code (for more on the program EOA character, see the description of the 
FORWARD macro). Byte 19 contains a character specifying the priority of the 
message. The remaining portion of the message is text and is followed by the 
EOT character (which must be inserted by the station operator to indicate the end 
of the message). 

If LC=OUT is coded in the STARTMH macro, all control characters (including 
the machine EOA) are deleted after the message is placed in buffers; the buffers 
must be large enough to accommodate these characters. If the user wishes to 
insert time-received, date-received, and output-sequence information into his 
message header, he must code the RESERVE= operand of the line group DCB 
macro to specify the number of bytes to be reserved in his input buffer. (The user 
may also insert data into his message by the MSGEDIT macro; no buffer space 
need by reserved for data inserted by MSGEDIT.) 

Figure 10 shows how the message would look when transmitted to a destination 
station. In this example, the Message Control Program inserted time-received and 
date-received information in the header. The time-received information in bytes 
26 through 33 indicates that the message was received at 1 1 hours, 30 minutes, 
and 45 seconds on the date specified in bytes 19 through 24, which is November 
5, 1969. Insertion of this information moved the priority data to byte 35. The 
message is then queued by priority on the message queue for the destination 
station. When the message reentered main storage before transmission to the 
destination stations, the Message Control Program placed a blank followed by the 
output sequence number in bytes 36 through 40 of the header. TCAM sends a 
series of control characters (ending with the machine EOA) before sending the 
message to its destination; TCAM supplies an EOT character when the 
MSGFORM macro is coded. 
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Figure 10. Sample Format for an Outgoing Message 

A Message Handler is divided into two main groups of macro instructions, the 
incoming group and the outgoing group. The incoming group handles all messages 
that arrive at the Message Control Program; these messages may originate from 
any of the lines, line groups, or application programs that are assigned to have 
their messages operated on by the Message Handler. The outgoing group handles 
messages being sent from the Message Control Program to any of the lines, line 
groups, or application programs. 

Each of the two groups of a Message Handler may be divided into subgroups. The 
incoming group may have the following subgroups: 

• inblock subgroups, which process all incoming message segments; 

• inheader subgroups, which handle only those incoming message segments that 
include all or part of a message header; 

• inbuffer subgroups, which process all incoming message segments; and 

• inmessage subgroups, which are executed after a complete message has arrived 
at the CPU. 

The outgoing group has three possible subgroups: 

• outheader subgroups, which handle only those outgoing message segments that 
include all or part of a message header; 

• outbuffer subgroups, which process all outgoing message segments, and 

• outmessage subgroups, which are executed after a complete message has been 
sent. 

Functions Performed by MH Subgroups 

The following presents an overview of MH organization and describes typical 
functions performed in each type of subgroup. The words in parentheses are the 
names of the MH macros that perform the functions described. 



Macro or Subgroup 



STARTMH 



Function 

Determines whether this is an incoming or an outgoing 
message, and routes it to the appropriate MH group. 



Inblock Subgroup 



Operates on each incoming segment: 

• Determines whether the message should be translat- 
ed to EBCDIC (CODE) 

• Counts incoming messages or message segments 
(COUNTER) 



< 
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Inheader Subgroup 



Inbuffer Subgroup 



Inmessage Subgroup 



Outheader Subgroup 



> 



Edits header fields and text across buffer bounda- 
ries (MSGEDIT, MSGFORM) 
Constructs logical messages 



Operates on an incoming message header: 

• Determines whether the message should be translat- 
ed to EBCDIC (CODE) 

• Determines the message origin and destination 
(ORIGIN, FORWARD) 

• Checks the incoming sequence number 
(SEQUENCE) 

• Determines the message priority 
(PRIORITY) 

. Edits header fields (MSGEDIT) 

• Moves data to be broadcast into a common data 
area and schedules a broadcast operation 
(COMMBUF) 



Operates on each segment of an incoming message: 

• Counts incoming message segments 
(COUNTER) 

• Edits text (MSGEDIT) 

• Checks the length of incoming messages and 
terminates reception for messages that are too long 
(CUTOFF) 

• Moves data to be broadcast into a common data 
area and schedules a broadcast operation 
(COMMBUF) 



Specifies actions to be taken after the entire message 
has been received: 

• Logs the message (LOG) 

• Cancels the message or the last block of the mes- 
sage (CANCELMG) 

• Returns error messages to the originating station 
(ERRORMSG, MSGGEN) 

• Retries to contact a switched station (RETRY) 



Operates on an outgoing message header: 

• Inserts the date and time into the outgoing header 
(DATETIME) 

• Assigns an outgoing sequence number to the 
message and inserting it in the header 
(SEQUENCE) 

. Edits header fields (MSGEDIT) 

• Determines whether the message should be translat- 
ed to line code (CODE) 
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Outbuffer Subgroup 



Determines whether line-control characters should 

be inserted into the outgoing message 

(MSGFORM) I 



Operates on each segment of an outgoing message: 

• Counts outgoing message segments 
(COUNTER) 

. Edits text (MSGEDIT) 

Outmessage Subgroup 

Specifies actions to be taken after the entire message 
has been sent: 

• Logs the messrage (LOG) 

• Sends an error message to the destination station 
(ERRORMSG, MSGGEN) 

• Intercepts messages to the destination station 
(because, perhaps, the station is inoperative) 
(HOLD) 

More than one subgroup of a particular kind may be included within a group to 
accommodate variations in handling that may be required by various kinds of 
messages (see Variable Processing within a Message Handler in this chapter). 

Delimiter macros identify the beginning and end of different MH groups and 
subgroups. The STARTMH macro identifies the beginning of an MH. 
INBLOCK, INHDR, INBUF, and INMSG respectively identify the beginning of | 

the inblock, inheader, inbuffer, and inmessage subgroups of the incoming group. \i 

INEND identifies the end of the incoming group. OUTHDR, OUTBUF, and 
OUTMSG respectively identify the beginnings of the outheader, outbuffer, and 
outmessage subgroups of the outgoing group, while OUTEND identifies the end 
of this group. The delimiter macros are discussed in detail later in this chapter. 

A minimum Message Handler consists of a STARTMH macro and either an 
incoming group or an outgoing group (either group may be omitted, as when the 
incoming group is omitted for an output-only line). If the outgoing group is 
omitted, the OUTEND macro must be coded to preserve addressabihty. The 
incoming group must precede the outgoing group if both are included in an MH. 

The following rules govern the arrangement of subgroups within a group: 

L If there is an incoming group not handling logical messages or editing data 
across buffer boundaries, an inheader subgroup is required as the first sub- 
group. If logical messages are being handled by this incoming subgroup, or if 
data is to be edited across buffer boundaries (MSGEDIT,MSGFORM), an 
inblock subgroup must precede the inheader subgroup. An inblock subgroup 
may be followed by another inblock subgroup or an inheader subgroup. All 
other subgroups of the incoming groups are optional. 

2. The first inheader subgroup in an incoming group may be followed by any 
combination of inheader and inbuffer subgroups. 

3. Inmessage subgroups, if present, must be the last subgroups in the incoming 
group. 

4. Any of the three types of subgroups for the outgoing group may appear as the 
first subgroup in the group. However, if an outmessage subgroup is the first 
subgroup, no outheader or outbuffer subgroup may appear in the group. 



( 
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5. Outheader and outbuffer subgroups may appear in the outgoing group in any 
order (that is, either subgroup may appear first and each may be specified more 
than once). 

6. Outmessage subgroups, if present, must be the last subgroups in the outgoing 
group. 

The sample Message Handlers in this chapter illustrate some of the ways in which 
subgroups may be arranged. 

The presence or absence of particular groups and subgroups within a given 
Message Handler depends upon the requirements of the user. Figure 1 1 summa- 
rizes the MH macros that may appear within a given subgroup. The user should 
familiarize himself with the functions of the macros shown in Figure 1 1 and decide 
which of these functions to incorporate into his Message Handler. His choice of 
functions will determine which subgroups will be present in his MH. For example, 
if he decides he needs the function provided by the CANCELMG macro in his 
MH, then he will require an inmessage subgroup. Some macros (CODE, 
COUNTER, LOG, for example) may appear in more than one kind of subgroup, 
but their functions vary according to the kind of subgroup in which they appear. 
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Figure 1 1 . Message Handler Subgroups and Macros 
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Selecting Message-Handler Functions 

Functional macro instructions perform the specific operations required for mes- 
sage segments being handled by the various subgroups of a Message Handler. 
Message segments are directed to the appropriate subgroup by the delimiter 
macros; the functional macros of the subgroup are then executed in the order in 
which they are specified within the subgroup. Functions provided by an MH 
include: 

• Message editing (insertion of date, time, and sequence number, insertion or 
removal of characters or character strings). 

• Validity checking (verification of source and destination codes and of sequence 
numbers in incoming message headers). 

• Routing messages to various destinations or alternate destinations, possibly by 
priority. 

• Maintaining counts and logs for message traffic on a line. 

• Error checking and handling (checking for errors in transmission and taking 
corrective action). 

• System control (interrogating or modifying activity on a system, line, or station 
basis, or specifying properties or limitations for messages). 

• Function selection (permitting dynamic selection of the functions to be per- 
formed on messages). 

MH Functions and Macros Defining the Functions 

The table below shows the various macros used to specify these functions. A 
brief description of the Message Handler functions provided by TCAM is given 
here. A complete description of these functions is found in the discussions of the 
individual macros in the Functional Macro Instructions section of this chapter. 

MH Functions Macros Defining the Functions 

Message Editing CODE, DATETIME, MSGEDIT, MSGFORM, 
SEQUENCE, SETEOM 

Validity Checking FORWARD, ORIGIN, SEQUENCE 

Routing COMMBUF, FORWARD, INITIATE, MHGET, 

MHPUT, MSGGEN, PRIORITY, REDIRECT 

Record Keeping CHECKPT, COUNTER, LOG 

Error Handling CANCELMG, CUTOFF, ERRORMSG, HOLD, 

MSGGEN, REDIRECT, RETRY, SLOWPOLL, 
TERRSET 

System Control CUTOFF, HOLD, INITIATE, LOCK, LOCOPT, 

SCREEN, SETEOF, MSGLIMIT, UNLOCK 



Message Editing 



Function Selection MSGTYPE, PATH, SETSCAN 



Six TCAM macro instructions— CODE, DATETIME, SEQUENCE, SETEOM, 
MSGEDIT, and MSGFORM — ^provide editing facilities. 



I 
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Validity Cliecking 



CODE, when specified in the inheader or inbuffer subgroup, translates the data in 
the buffer from the line code to EBCDIC, using a specified translation table. 
When specified in the outheader or outbuffer subgroup, translation is from 
EBCDIC to the line code. 

DATETIME inserts the date and the time at which the message is received by (or 
sent by) the MCP in the header. 

SEQUENCE, when specified in an outheader subgroup, inserts an output 
sequence number in the messages that are sent to a destination. 

MSGEDIT inserts or deletes a character or character string in the message. 

MSGFORM, when specified in an outheader subgroup, inserts blocking characters 
into outgoing messages, thereby dividing the messages into logical blocks of data. 
When specified in an inblock subgroup, characters are deleted at a user-specified 
interval. 

SETEOM defines the extent of a logical message. 



Three TCAM macro instructions — FORWARD, ORIGIN, and 
SEQUENCE — check the validity of fields in the message header. 

FORWARD verifies that the station codes specified as destinations in the message 
header are vahd destinations in the system. 

ORIGIN determines the station that entered a message by checking the origin 
field in the message header for the symbolic name of the station. The origin field 
is designated, during the design of the header and the Message Handler to contain 
the name of the originating station. 

SEQUENCE verifies that the input sequence number included in the message 
header by the station operator is valid; that is, that the number is one greater than 
the sequence number of the previous message from that station. To perform this 
function, SEQUENCE is included in an inheader subgroup. 



Message Routing 



Six TCAM macro instructions— COMMBUF, FORWARD, INITIATE, 
MSGGEN, PRIORITY, and REDIRECT — route messages to a particular destina- 
tion. 



COMMBUF routes broadcast messages to the destinations specified in the 
indicated TLIST macro. 

FORWARD routes messages to the destinations specified in the message headers 
or to the destinations specified by the FORWARD macro. 

INITIATE routes segments of messages to their destination as soon as they are 
received, without waiting for the whole message to arrive. 

MSGGEN generates a special response message and routes it immediately to 
either the originating or the destination station. The response message bypasses 
normal message handling, queuing, logging, and buffering functions. 
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Record Keeping 



Error Handling 



PRIORITY routes messages to their destinations according to priority levels 
specified either in the message header or by the PRIORITY macro. 

REDIRECT queues a message for an additional or alternate destination under 
certain error conditions, or unconditionally. 



Two TCAM macro instructions — COUNTER and LOG — keep records of the 
flow of messages in the system. 

COUNTER keeps a count of incoming or outgoing message segments or complete 
messages, depending on the subgroup in which the macro is issued. 

LOG places copies of segments or messages passing through the system on a 
sequential medium, such as magnetic tape. 



Nine TCAM macro instructions— CANCELMG, CUTOFF, ERRORMSG, 
HOLD, MSGGEN, REDIRECT, SLOWPOLL, TERRSET and UNLOCK when 
used in a message subgroup provide for error detection and handling. These 
macro instructions test for error conditions arising during transmission and 
handling of the message and take action accordingly. The nine macros are used in 
conjunction with a message error record, which is assigned to each message as it is 
handled. The meaning of each of the bits in the message error record is explained 
in Appendix B . Some error-handhng macros (CUTOFF, TERRSET) set bits in 
the message error record; the rest test the bits in the message error record. 

A five-byte bit configuration (called a mask ) is specified in some error-handling 
macros. When the macro is executed, the mask is compared to the message error 
record assigned to the message. If a 1 is detected in any bit position of both the 
mask and the message error record, the functions specified by the macro are 
performed. A is specified in a mask bit position when the error condition 
represented by the corresponding position in the message error record is to be 
ignored. (An operand of the error-handling macro may specify that the macro is to 
be executed only if all bits specified in the mask are on in the message error 
record.) 

The function specified by an error-handling macro may also be performed uncon- 
ditionally (that is, for all messages or message blocks, independent of the setting 
of the message error record) by either specifying a mask consisting entirely of 
zeros or not specifying a mask at all. 

The requirements of the application must be analyzed to determine which errors 
or conditions must be detected, and which can reasonably be ignored without 
degrading the performance of the system. The seven error-handling macro 
instructions provide varying methods by which corrective or control functions can 
be initiated when an error has been detected. 



CANCELMG cancels a message or a block if a specified error has occurred. 

CUTOFF checks for incoming buffers filled with identical characters (an indica- 
tion of station malfunction). In such a case, the appropriate bit is set in the 
message error record. CUTOFF also specifies the maximum number of characters 
allowed in a message; if the maximum is exceeded, reception is terminated and an 
error bit is set. 
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System Control 



ERRORMSG and MSGGEN send a specified message if a specified error has 
occurred. 

SLOWPOLL suspends further polling on a given Une when errors specified by the 
error mask occur. 

TERRSET sets a bit in the message error record to indicate, at the discretion of 
the user, that a user-defined error has occurred. 

HOLD suppresses the sending of messages to a station when an error specified by 
the mask has been detected; it is usually used to withold transmission to a inopera- 
tive station. 

UNLOCK removes a station from extended lock mode and optionally disables a 
switched connection if a specified error has occurred. 

REDIRECT sends a message to an additional or an alternate destination if a 
specified error has been detected. This function normally handles messages that 
cannot be sent to their intended destinations. 

RETRY tries again to contact a switched station. 

The FORWARD, ORIGIN, and SEQUENCE macro instructions set bits in the 
message error record when they detect an invalid destination, origin, and sequence 
number, respectively. 



Nine TCAM macro instructions— CUTOFF, HOLD, INITIATE, LOCK, ^ 

LOCOPT, MSGLIMIT, SCREEN, SETEOF, and UNLOCK— modify the tele- ^* 

communications system or provide dynamic control over the functions of the 
system. 

CUTOFF terminates transmission of an excessively long message. 

HOLD stops transmission of messages to a station known to be inoperative or 
unattended for a period of time making transmission undesirable. 

INITIATE sends message segments to their first destination before the entire 
message has been received and enqueued. 

LOCK maintains the connection between a station and an application program for 
the duration of a message and its response. This facility is used for fastest re- 
sponse during inquiry applications. 

LOCOPT provides access to fields of the option table, permitting examination and 
modification of the contents of the fields. 

MSGLIMIT limits the number of messages sent to or received from a station 
during a single transmission sequence. 

SCREEN modifies the WRITE operation for terminals with display screens. 

SETEOF indicates an end-of-file message for an appUcation program. 

UNLOCK removes a station from the LOCK condition. 



I 
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Delimiting Functions 



Function Modification 

Three TCAM macro instructions— MSGTYPE, PATH, and SETS CAN— permit 
modification of the functions of the Message Handler. The first two macros 
provide for variations in processing by the MH for different types of messages. 
SETSCAN permits modification of the scan pointer setting (discussed below) to 
allow processing of a field in the header in some order other than the normal 
sequential order. 

The STARTMH delimiter macro provides end-of-block checking for hardware 
and logical errors, and takes appropriate user-specified action when such errors 
are detected. These errors cause bits to be set in the message error record. 
STARTMH also provides for the automatic deletion of certain line-control 
characters, so that the user need not concern himself with them. Of the remaining 
delimiters, INBLOCK, INHDR, INBUF, INMSG, OUTHDR, OUTBUF, and 
OUTMSG provide path-switching facilities. Only the INEND and OUTEND 
delimiter macros have no functional capabilities. 

Order of Macro Specification 

Functional macros relating to an entire message segment (that is, MSGEDIT, 
LOG) may appear at any point within the subgroup in which they are used. The 
MSGFORM, MSGEDIT, and SETEOM functional macros should be specified in 
the inblock subgroup to process data across buffer boundaries. Macros relating to 
specific header fields (that is, ORIGIN, DATETIME) should appear in the same 
order within the inheader or outheader subgroup as the header fields appear 
within the header. In planning a format for message headers, the user may 
arrange the various header fields in any desired order within the header; the 
corresponding macros that act on those fields must be placed within the subgroup 
in the same order. These order-dependent macros involve either: 

• inserting a new field in the message header (for example, DATETIME), 

• making a decision at some point during header processing (for example, 
MSGTYPE), or 

• using a TCAM scanning routine to determine the contents of a specific field 
(for example, ORIGIN). 

The order in which macros are issued to act on specific header fields is important 
since a pointer (known as the scan pointer ), refers to the proper field when each 
macro gains control to act on that field. 



The Scan Pointer 



In handling a buffer, TCAM maintains a pointer at the current field in the 
message header. Some macro instructions use this pointer to locate the field on 
which they act and automatically move the pointer to the next field before passing 
control to the next macro. The user must be aware of the positioning of the scan 
pointer as he designs his Message Handler. 

There are basically two types of TCAM macro instructions that move the scan 
pointer automatically, without intervention by the user. Examples can be found in 
Figure 12. 

1. Certain macros (for example, SETSCAN, FORWARD) move the scan pointer 
until a user-specified character string is found. After these macros have com- 
pleted execution, the scan pointer is positioned on the last character acted 
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upon. In this case, it is assumed that the next character string is the field to be 
looked at by the next field-dependent macro in the Message Handler. 
2. Other macro instructions move the scan pointer a certain number of characters. ; 

There are three ways this number is determined. 

a. With certain macros (FORWARD, ORIGIN, SETSCAN), the user may 
specify expHcitly a number of nonblank characters to be considered as the 
next field. When execution of a macro is complete, the scan pointer is 
positioned on the last character that satisfies the count. 

Example: 

FORWARD DEST=3. If a destination field in a header reads NYbC, the 

scan pointer points to the C. 

b. Some macro instructions may be concerned with fields of varying length, 
such as FORWARD and ORIGIN. The scan pointer is moved past any 
blanks that might precede the field. The field is then scanned for a blank 
delimiter. When such a macro is completed, the scan pointer points to the 
character immediately preceding the blank delimiter that designates the end 
of the field. 

c. Some macros are concerned with fields whose length is specified imphcitly 
by coding the contents of the field in the macro itself. SETSCAN may 
search for a field with contents that match those specified in the macro; the 
position of the scan pointer after the macro executes is described in the 
discussion of the macro. The INITIATE, LOCK, MSGTYPE, PATH, 
PRIORITY, SCREEN, SETEOF, and UNLOCK macros have an optional 
conchars operand; when this operand is specified, the scan pointer is moved 
past any blanks preceding the next field in the message, and the contents of 
the field are compared with the conchars string. If the field and the conchars 

string match, the scan pointer points to the last character of the field; other- ^ 

wise, it is returned to the position it occupied before the comparison was l| 

made. 



( 
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The DATETIME macro causes the header contents to be shifted 16 spaces 


left to make room for the date and time. These are inserted and the 
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Figure 12. Scan Pointer Movement 



When a message segment is received for processing in an incoming group of an 
MH, the space reserved for expansion by the RESERVE= operand of the line 
group DCB macro is moved to the front of the segment and the scan pointer is 
positioned at the last reserved byte. If no reserve bytes were specified, the scan 
pointer points to the last byte of the buffer prefix. The buffer is then examined 
for the presence of a machine EGA sequence. If such a sequence is found, the 
scan pointer is moved to the last byte of the sequence. However, the poUing 
character used when the Auto Poll feature is active is not considered part of the 
machine EGA sequence. 



For an incoming message, the scan pointer is not necessarily at the end of the 
header when the inheader subgroup finishes executing. The header may have 
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additional fields that are to be operated upon by an outheader subgroup when the 
message is removed from its destination queue. In this case, when the message is 
removed from the queue, STARTMH and OUTHDR reposition the scan pointer 
to the last remaining reserve byte or, if there are no more unused reserve bytes, to 
the last byte of the prefix. If the user wishes to use an outheader subgroup to 
process the remaining fields of his header, he may use the SETSCAN macro to 
reset the scan pointer to the last byte of the last field processed by the inheader 
subgroup. 

Macro instructions in an MH should be placed in the same order within a sub- 
group as the fields of the header on which they act. The scan pointer controls 
access to these fields, progressing across the header from left to right as the 
various macro instructions are executed. The user may employ the scan pointer 
(using the SETSCAN macro) in his own routines to perform additional header 
analysis. However, he must take the responsibility of positioning the scan pointer 
to its proper position before executing the next TCAM macro. 

Handling Logical Messages 

Message transmission as discussed in other sections of this book defines each 
transmission from a station as a message. This may not correspond, however to 
the user's concept of a message. Some stations accumulate data in buffers before 
it is transmitted and permit no more than one buffer's worth in a transmission. 
Thus, if a user's message is longer than the buffer size, his message requires two or 
more transmissions. What the user sees in this instance as one message is seen by 
TCAM as several. Alternatively, some stations permit many units of data, such as 
cards, to be batched and sent as a single transmission. TCAM takes this to be one 
message, whereas to the user it may be many. 

Logical message definition enables TCAM to process messages on a logical basis 
as defined by the user independently of any physical boundaries imposed by the 
associated transmissions. When the user defines his messages as logical, TCAM 
performs either a blocking or a deblocking operation and then processes and 
queues the resulting data as a single message. For instance, when a single trans- 
mission contains several logical messages, TCAM deblocks the messages and 
independently processes and queues each. 

The concepts of TCAM design discussed in other sections of this book are not 
modified for handling logical messages; that is, messages received from stations 
are still processed through a Message Handler and queued in destination queues 
from which they are sent to an application program or another station. The 
execution of inheader, inmessage, inbuffer, outheader, outmessage, and outbuffer 
subgroups remain the same. The inblock subgroup processes logical messages in 
the incoming group. The INBLOCK delimiter macro instruction identifies the 
beginning of an inblock subgroup. 

The SETEOM macro instruction, executed in the inblock subgroup, deblocks and 
blocks incoming data to form logical messages according to user specifications. 
The inblock subgroup is specified after the STARTMH delimiter macro and 
before the inheader subgroup. The inblock subgroup and the INBLOCK macro 
instruction are described in Structure of the Message Handler and Delimiter 
Macro Instructions , respectively. 

See Mid-Batch Recovery in the section TCAM I/O Error-recovery Procedures 
for a discussion of treating permanent I/O errors detected in incoming and 
outgoing multiblock messages. 
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Logical Message Formats 



The types of logical messages that may be included in a TCAM system depend 
upon the characteristics of the physical transmissions involved. These characteris- 
tics determine whether incoming messages are blocked or deblocked to form 
logical messages to be handled by the MCP. 

For instance, some devices may impose a physical limit on the size of a transmis- 
sion, such as the IBM 2740 Model 2 Communication Terminal that transmits data 
equivalent to the size of its buffer, and input from a card reader that also may 
require fixed-length messages. Other devices may not impose such physical 
limitations, such as the IBM 1060 Data Communication System, and a 2780 Data 
Transmission Terminal that features multiple-record transmissions. Examples of 
logical messages formed from both kinds of these devices follow. In the examples, 
a physical transmission refers to the amount of data entered on a line during an 
entire transmission sequence (from the first byte of data in a message to the 
end-of -transmission character). 



Blocking Incoming Messages 



Incoming messages can be blocked to construct logical messages to be handled by 
the inblock subgroup. No incoming transmission will contain all the data that is to 
constitute the final logical message. 

In blocking two incoming physical transmissions to construct a single logical 
message, the user may specify that TCAM truncate any data appearing after the 
end of the logical data (after the EOM indicator) in the second physical transmis- 
sion; this is accompUshed by specifying PROCESS=NO on the SETEOM macro 
in the MH handling these physical transmissions. 

Example: 

Constructing a logical message by blocking two physical transmissions. Input is 
from an IBM 2740 Model 2, where the size of the logical message is greater than 
the terminal buffer size. For this type of message, the user specifies that only one 
logical message is to be processed (resulting in truncation of any data in the 
second buffer following the end of the logical message). 



E OT 



■ Logical Message ■ 



E E 

O o 

M T 



-Truncated 



In the example above, blocking is done on incoming data from a device that 
imposes a physical limit on the amount of data that may be entered for a single 
transmission sequence. The next example illustrates blocking a series of incoming 
logical blocks of data to construct a single larger logical message. The incoming 
logical blocks of data are all included in a single physical transmission. This 
procedure requires that the SETEOM macro specify PROCESS=NO. 

Example: 

Constructing a logical message by blocking multiple logical messages. Input is 
from an IBM 1060 Data Communication System where incoming logical messages 
are blocked according to the location of a user-specified character (EOM indica- 
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tor) that delimits the end of the last logical block to be included in the logical 
message being constructed. Incoming logical messages are referred to as blocks. 
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Deblocking Incoming Messages 



Deblocking always occurs on incoming data that consists of variable-length logical 
blocks of data separated by EOM indicators. The last EOM indicator in the last 
logical block of data is followed by an EOT line control character (the 
EOM/EOT sequence indicates to TCAM that this is the end of the physical 
transmission). Each imbedded logical block of data in a given physical transmis- 
sion may contain a header and may be extracted for processing and routing to a 
particular destination queue. The boundaries of each logical block are determined 
when the buffer containing a block passes through the input MH and is processed 
by the SETEOM macro instruction. Discussions in other parts of this book on 
length and format of messages apply also for deblocked logical messages. 



Example: 

Extracting logical messages by deblocking logical blocks of data in a physical 
transmission. Input is variable records from an IBM 2780 Data Transmission 
Terminal. Each variable input record on a card is delimited by a character that 
signifies EOM (end of logical message). 
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If part of a physical transmission has been received from a station, output to that 
station is not sent until the EOM/EOT sequence is received from the station 
indicating the end of the physical transmission. 

Converting Incoming Data to Logical Messages 

Conversion of incoming data in a physical transmission to logical message is 
achieved by using the SETEOM macro instruction in the inblock subgroup of an 
MH handling incoming messages. The SETEOM macro instruction is discussed in 
Functional Macro Instructions. 

The user specifies on the SETEOM macro which delimiter character or which 
length of data, or both, determine the limits of a logical message. When both are 
specified, the first condition met determines the end of a logical message. The 
SETEOM macro also permits the user to remove EOM characters from incoming 
logical messages. 
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When TCAM detects an EOM condition in an incoming transmission, it needs to 
know how to handle the data, if any, following the EOM indicator. The SETEOM 
I macro indicates to TCAM whether it is to discard any remaining portion or to 

process it as the first buffer of another message. Subsequent buffers begin 
processing at the INBLOCK deUmiter macro instruction. 

Execution of SETEOM may force an EOM condition; for instance, if the input to 
an MH is cards containing variable-length records (such as 2780 batch input), and 
the last card in the hopper ends in the middle of a message, TCAM assumes an 
EOM condition and the last card is the end of the message. Another instance of 
forcing an EOM condition is the occurrence of a permanent transmission error 
before TCAM detects the User-specified EOM. In this case an EOM is forced for 
the last buffer successfully transmitted. In a dial network, for instance, if an 
operator hangs up before an entire logical message is entered (or if a disconnec- 
tion is caused by some other means), TCAM forces an EOM condition for the 
message being entered. In either of these cases of forced EOM, the logical 
message is processed through the MH. 

TCAM, however, does not always assume an EOM condition. For instance, if 
input is from a 2740 Model 2 and the message is directed to an MH that is to 
construct a single logical message from two or more physical transmissions 
(PROCESS=NO is specified on the SETEOM macro), the input message must 
contain an EOM character in the second (or a subsequent) buffer. Otherwise, the 
2740 Model 2 cannot accept further output from the CPU (TCAM is still waiting 
for the user-specified character that designates the end of the logical message). 

The user may not issue successive SETEOM macros in the same Message Handler 
^, in order to process nested logical messages. That is, if a SETEOM macro is used 

¥ to extract a logical message (message A) from a series of logical messages entered 

during one physical transmission, another SETEOM macro cannot be issued to 
find further logical messages embedded within message A. 

The buffer trace facility, provided by the TRACE= and COMWRTE= operands 
of the INTRO macro instruction, provides a dump of deblocked logical messages. 

Logical Message Flow Within the System 

Message flow in a TCAM system remains the same for logical messages as for 
physical messages (message flow for physical messages is discussed in Message 
Flow Through a Message Handler in this chapter). Incoming data is processed 
through an MH where it is converted into logical messages by the SETEOM 
macro. The logical messages are then routed to their destination queues independ- 
ently of any incoming physical message boundaries. Figures 13 and 14 show 
examples of message flow within the system when logical messages are being 
handled. 

In Figure 13, message flow is shown for a logical message that is constructed from 
two physical transmissions (SETEOM specifies PROCESS=NO, resulting in 
truncation of data following the EOM character). The EOM character is con- 
tained in the second physical transmission. 

1. The station T responds to polling and enters data for the first physical trans- 
mission to the CPU. This first physical transmission fills the buffers that are 
allocated and deallocated according to the program-controlled interruption 
option selected for the station (see the PCI= operand of the line group DCB 
I macro instruction) . 
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Figure 13. Flow of Logical Message Formed by Blocking Two Physical Transmissions 

2. All buffers of the first transmission are processed through the inblock sub- 
group, and the SETEOM macro instruction is executed for them. 

3. The first transmission does not contain an EOM character. The buffers pass 
through the remainder of the MH and are queued to their destination, but 
TCAM considers the logical message to be incomplete; that is, the last buffer 
of this transmission is not processed as the last buffer of the logical message. 
However, the line is reactivated. 

4. The line is now available for any station that has data to enter, including 
station T, which is polled first. If station T is not ready to enter data for the 
second transmission, another station is polled. (TCAM line scheduling is the 
same as for a TCAM system that is not handling logical messages.) 

5. When the second transmission from terminal T arrives at the CPU, its buffers 
are passed to the MH in the same manner as the first transmission. 

6. These buffers are processed by the SETEOM macro; they proceed through 
the remainder of the MH and are queued until the EOM condition is satisfied. 
One difference in MH processing of logical messages is that the second 
transmission is not a new message, but the continuation of the logical mes- 
sage. Therefore, the first buffer of the second transmission is not processed 
as a header buffer, but as a text buffer. 
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7. When TCAM detects the EOM, the remaining portion (if any) of the current 
buffer is truncated. The buffer containing the EOM character is processed by 
the rest of the MH as the last buffer of the message. 

8. After TCAM detects the EOM indicator, subsequent buffers of the same 
transmissionare truncated also. They are returned to the buffer pool without 
being processed by the MH and without being queued. 

9. The inmessage subgroup is executed for the logical message when its last 
buffer has been handled. This inmessage processing, performed for the 
buffer containing the EOM, is delayed until block checking is performed for 
the block containing the EOM. 

10. The line is then reactivated and the logical message is ready to be sent to its 
destination (either an application program or a station). 

In Figure 14, message flow is shown for logical messages formed by extracting two 
logical messages entered in a single physical transmission (such input might come 
from an IBM 1060 Data Communication System or an IBM 2780 Data Transmis- 
sion Terminal). 

The EOM character appears as part of the input stream at the end of each logical 
message; the last EOM is followed by EOT. (The SETEOM macro specifies 
PROCESS=YES, resulting in successive logical messages being handled by the 
incoming MH until an EOM is followed by an EOT.) 

1. Station K responds to polling and enters its variable-length messages in a single 
transmission sequence. The message fills -the buffers, which are allocated and 
deallocated according to the program-controlled interruption option selected 
(see the PCI= operand of the line group DCB macro). This example requires a 
value of N or X for the PCI= operand. 

2. All buffers containing any data of the first logical message are processed in the 
inblock subgroup where they are examined by the SETEOM macro. 

3. The first buffer of the entire incoming transmission is processed through an 
inheader subgroup as the header buffer for the first logical message. 

4. TCAM detects the EOM character that delimits the first logical message and 
gets a new buffer in order to separate the first logical message and any remain- 
ing portion of the EOM buffer. This remainder becomes the header buffer for 
the second logical message and is assigned to the MH where processing begins 
at the beginning of the inblock subgroup. 

5. The buffer containing the EOM character that ends the first logical message is 
the last buffer of the first logical message; it proceeds through the MH and 
causes the inmessage subgroup to execute. Macros in the inmessage subgroup 
that are executed for the first logical message also handle error conditions for 
all the input data since block checking is performed before processing later 
portions of the first logical message. 

6. The first logical message is ready to be sent to its destination. 

7. Processing of the second logical message is done just as it was for the first. 
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Figure 14. Flow of Logical Message Formed by Deblocking a Physical Transmission 



Message Headers for Logical Messages 

In a TCAM network that does not define logical messages (see the SETEOM 
macro), a header begins each physical transmission. This concept is modified 
when the SETEOM macro is coded to define logical messages, so that a header 
begins each logical message . Thus, if a logical message is constructed from two 
incoming physical transmissions (such as blocking two physical transmissions from 
a 2740 Model 2), only one header is processed for the logical message. 
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In this example, the SETEOM macro specifies PROCESS=NO. The first buffer 
of the second physical transmission is processed as a continuation of the logical 
message, that is, as a text buffer. 



If the user appUcation is such that the size of the messages being entered coincides 
with the limit imposed by the input device (such as buffered terminals and some 
card readers), blocking is not required; thus, the number of headers needed is the 
same for both physical transmissions and logical messages. 
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In this example, the SETEOM macro specifies PROCESS=NO. A physical 
transmission is equivalent to a logical message, and the same number of headers is 
required for physical transmissions as for logical messages. 

The preceding examples consider header requirements for entering individual 
logical messages, where one or more physical transmissions are required. 
Suppose/, however, that a network includes devices such as the IBM 1060 Data 
Communication System and the IBM 2780 Data Transmission Terminal (with the 
multiple record transmission feature), where a single physical transmission com- 
prises many logical blocks of data (batch input), each to be treated as a message. 

In a network where the user does not define logical messages, batch input requires 
a single header. However, by defining logical messages with the SETEOM macro, 
each incoming, imbedded logical block of data is a message, and each block 
requires a header. 
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In this example, if the user does not define logical messages for his system, his 
batch input requires only one header, and TCAM processes all the data in the 
physical transmission on the basis of the single header (that is, TCAM treats the 
input as a single message). However, if user requirements dictate that the data in 
this batch input can best serve the purpose by including logical messages, then 
each imbedded logical block must start with a header for TCAM to initiate header 
processing for each logical message (thus, TCAM can treat each incoming logical 
block of data as a message, and multiple destinations can be defined for the batch 
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input from a station). The SETEOM macro must specify PROCESS = YES in 
order for TCAM to process the individual logical messages described in this 
example. 

Coding Considerations for Logical Message Use 

This section considers the coding requirements for the user who defines logical 
messages for his TCAM network. The table below lists the macros and only those 
operands that need to be considered for defining data sets and stations; it also Usts 
some delimiter and functional MH macros that need to be considered. The table 
lists only those macros and operands concerning logical messages. Other sections 
of the book contain complete descriptions of these and other macro instructions 
(see the Macro Directory in the front of this book). 

Of the macro instructions Usted below, only the SETEOM functional macro is 
limited to use with logical message handling. The remaining macro instructions 
may be used in handling physical transmissions in a TCAM system that does not 
define logical messages; of these, however, some operands are restricted to use 
with logical message (PCI=X on the line group DCB macro, LMD= on the 
TERMINAL macro, and LMD= on the STARTMH macro). 
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Code 
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Macro 

line 
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Operand 




Remarks 

X specifies that after a buffer 
is filled (receive operations) 
or emptied (send operations), a 
PCI occurs during the filling 
or emptying of the next buffer. 
The first buffer is not deallo- 
cated, but a new buffer is allo- 
cated. Buffer deallocation 
occurs at the end of transmis- 
sion, or when an EOB/ETB control 
character is sent, if EOB/ETB 
checking is specified in the 
STARTMH macro. 
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PCI=N or X must be specified if 
the SETEOM macro specifies 
PROCESS=YES, in order to ensure 
that logical messages are not 
deblocked until block checking 
is performed. Otherwise, a 
logical message containing an 
error could be routed to its 
destination. 

This operand specifies whether 
logical messages are to be 
transmitted either to or from 
this station. LMD=YES must be 
coded. 

Provides mid-batch recovery on 
input and output operations on 
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logical messages in a TCAM network. 
Requires that LMD=YES be specified 
on this TERMINAL macro for any station 
entering or accepting logical messages 
and for which mid-batch recovery is 
desired. LMD=YES must be specified on the 
STARTMH macro of the MH handling logical 
messages (for incoming operations, 
LEVEL =BLK must be specified on the 
CANCELMG macro in the inmessage 
subgroup; for outgoing operations, 
LEVEL=BLK must be specified on the HOLD 
macro in the outmessage subgroup). 
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Note: // stations specifying 
either LMD^YES or MB=YES are 
defined on the same line with 
stations (other than concentrators, 
see Defining the Network in 
Appendix J that do not specify 
either of these two operands, the 
first TERMINAL macro used to define 
stations on this line must be for a 
non-concentrating terminal not 
specifying either of these two 
operands. 

This operand specifies whether 
logical messages are to be 
handled by this MH. LMD=YES 
must be coded. 
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includes a SETEOM macro for 
handling logical messages, or 
includes a MSGEDIT macro for 
handling character strings that 
cross buffer boundaries, or 
includes a MSGFORM macro for 
deleting multiple character 
strings on a count basis. 



The inblock subgroup must 

precede the inheader subgroup. 

Functional macros that may 

be coded in this subgroup are CODE, 

COUNTER, LOG, LOCOP, MSGEDIT, 

MSGFORM, MSGLIMIT, PATH, SETEOM, and 

TERRSET. If coded before the 

SETEOM macro they execute for all 

the data in the physical transmission; 
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if coded after SETEOM, they execute 
individually for logical messages. 

Specifies mid-batch recovery for errors 

detected in incoming multiblock 

messages. If mid-batch recovery is 

required, LEVEL=BLK must be specified in 

the inmessage subgroup (specify only 

once; CANCELMG must be the first functional 

macro in the subgroup). 

Translates data in the buffer 

being handled and tests for operator 

commands. The following considerations 

apply for logical messages that are extracted by 

deblocking data in an incoming physical 

transmission. 



COUNTER 



opfield 



• When coded before the SETEOM macro, all data 
related to this transmission is translated. Logical 
messages are to be checked for operator control 
characters,another CODE macro must be coded 
in the inheader subgroup (and it must specify 
NONE). 

• When coded after the SETEOM macro, 
functions the same as for physical transmissions 
(translates,but must be coded in the inheader 
subgroup to check for operator control charac- 
ters). 

Counts either logical message 
segments or physical message segments, 
depending on its position relative 
to the SETEOM macro and whether 
the PROCESS = operand of SETEOM 
specifies YES or NO. 

When SETEOM specifies PROCESS=NO, 
all resulting logical messages are 
counted. 



/4 

i ' 



HOLD 



LEVEL= 



[MSGl 
LBLKJ 



When SETEOM specifies PROCESS=YES, 
the position of COUNTER relative to 
SETEOM determines what is counted. 
IF COUNTER is coded before SETEOM, 
the count reflects all the buffers 
forwarded to the MH in the transmission 
sequence. If coded after SETEOM, 
the count reflects each buffer of each 
resulting logical message. 

If this operand is omitted or if 

it specifies MSG, the HOLD macro 

provides the same function as 



i 
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for physical messages (see the 
description of the HOLD macro in 
Functional Macro Instructions ). 

LEVEL =BLK specifies mid-batch 
recovery for errors detected in 
outgoing multiblock messages to 
a switched station. If mid-batch 
recovery is required, LEVEL=BLK 
must be specified in the outmessage 
subgroup (specify only once; HOLD 
must be the first functional macro 
in the subgroup). 



LOCK 



Requires that PROCESS = NO be 
coded on the SETEOM macro. Used 
only for a logical message con- 
structed by blocking two or more 
incoming physical messages. Provides 
the same functions as for physical 
messages, except on a logical message 
basis. Lock is achieved after EOM 
character is detected (implying that 
multiple physical transmissions may have 
been received). See the description 
of the LOCK macro in Functional 
Macro Instructions. 



MSGFORM 



Removes line control characters (on a 
count basis) from incoming messages. 
MSGFORM must be coded in the inblock 
subgroup before any other macro that 
might cause data movement. 



MSGLIMIT 



SETEOM 



ENDCHAR=rchars "I 
LppfieldJ 



Provides the same function as 
for physical messages. The count 
for MSGLIMIT is updated for each 
physical transmission sequence. 

This macro, restricted to use in 
the inblock subgroup, controls 
the amount of data in logical 
messages, determines what is 
done with data following EOM, 
and permits removal of EOM char- 
acters. 



The ENDCHAR= operand specifies 
the character or character 
string used to delimit the mes- 
sage. This operand is required 
if the LENGTH = operand is not 
coded (otherwise, it is optional). 
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chars specifies one to eight 
nonbiank characters in either 
character (C* ' or CLn' ') or 
hexadecimal (X' ' or XLn* ') 
format 

opfield is the name of a field 

defined by an OPTION macro containing 

the character or character string. 

The first byte of the option field 

contains the length of the delimiter, 

followed by the delimiter. 



LENGTH= 

((integer (,opfield2) 



Jopfieldl* 



Specifies the length of the mes- 
sage. Must be specified if the 
ENDCHAR= operand is not coded; 
otherwise, this operand is 
optional, integer specifies 
a decimal integer that may be 
up to 65535. 



PROCESS=(YESl 
(NO j 



opfield 1 is the name of a halfword 
defined by an OPTION macro con- 
taining the length of the message. 

opfield! is a halfword option 
field set to zero (counts bytes 
already received). 

Determines whether any incoming 
data following EOM is processed 
or discarded. 



YES causes data following the 
EOM to be processed in the same 
manner as the previous data. 



REMOVE=jYES) 
\NO I 



NO causes processing for the 
first logical message only. 

Removes EOM characters from 
buffers containing logical mes- 
sages (or partial logical mes- 
sages). 



YES causes EOM characters to be 
removed from incoming buffers 
containing parts of one or more 
logical messages. 



NO causes EOM characters to remain 
in the buffer in which they appear. 



( 
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Message Flow Through A Message Handler 

Figures 15 and 16 illustrate the overall flow of a message through Message 
Handlers written for two representative TCAM applications. After briefly 
considering the overall flow, the path of a message within a single incoming or 
outgoing group is described. If logical messages are being handled, see Logical 
Message Flow Within the System in the preceding section. 

Figure 15 illustrates the flow through a single MH of a message to be switched 
from one station to another that requires no processing by an application program. 
The incoming message is routed by STARTMH to the incoming group of the MH 
assigned to the Une (by the MH= operand of the DCB macro for the line group in 
which the line is included). After being processed by the incoming group, the 
message is placed on the destination queue for the station to which the message is 
to be routed. This queue may be on a direct-access storage device, or it may be in 
main storage. TCAM obtains messages from the destination queue on a first- 
ended first-out basis within priority groups. STARTMH then routes the message 
from the destination queue to the outgoing group of the MH assigned to the line 
on which the destination station is located. After being handled by the outgoing 
group, the message is transmitted to the destination station. 



Message 
entered at 
remote 
station 



N 



Message 
accepted at 
destination 



Incoming 
Group of MH 
for line group 



Destination 
queue 



Outgoing 
Group of MH 
for line group 



Figure 15. Message Flow for a Switched Message 

Figure 16 illustrates the more complicated message flow for a message that is 
received, routed to an application program, and then transmitted to a destination 
station. The message is processed first by the incoming group of the MH handling 
messages for this line, then placed on the destination queue for the appUcation 
program (this queue is created by a TPROCESS macro). The outgoing group 
created especially for the application program and assigned to it by the MH= 
operand of a PCB macro processes the message when it is removed from the 
destination queue; the message is then placed on the read-ahead queue , a special 
queue to which access is gained by GET or READ macros issued in the applica- 
tion program. After being processed by the application program, the message is 
returned to a process queue by PUT or WRITE macros and is handled by the 
incoming group of the MH assigned to the application program by the MH= 
operand of the PCB macro for that application program. The message is routed 
by this incoming group to the destination queue for the station that is to accept 
the message. It is then handled by the outgoing group of the MH assigned to the 
line and transmitted to the destination station. 
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In Figure 16, two incoming and two outgoing groups are used in iiandling the 
message. One incoming and one outgoing group are assigned to the Une, and one 
of each group is assigned to the appUcation program. The user might provide 
these groups by designing one MH for his Une and another for his application 
program; or he might design a single MH and assign it to both the line and the 
apphcation program. This single MH would have some subgroups that would be 
executed only for messages coming in from or going to a station on the line, and 
other subgroups that would be executed only for messages being sent to or 
received from an appUcation program. For a description of how this selective 
execution is accomplished, see Variable Processing within a Message Handler in 
this chapter. 
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Figure 1 6. Message Flow for a Message that is Processed by an Application Program 



For a more thorough description of the flow of a message through a TCAM 
system, see Message Flow within the System in the TCAM Concepts and 
Facilities publication. 



Message Flow within an MH Group 

That portion of a message contained within one main-storage buffer is caUed a 
message segment . When a message segment arrives for processing by a Message 
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Handler, STARTMH determines whether the segment is part of an incoming or 
outgoing message and routes it to the incoming or outgoing group, as appropriate. 
STARTMH also determines whether the segment contains part of a multiple- 
buffer header. A multiple-buffer header is a message header that occupies more 
than one buffer. Message segments containing part of a multiple-buffer header go 
through the inheader and outheader subgroups in a special manner, described 
below. 

The flow through an MH assigned to a Une group of a message that does not have 
a multiple-buffer header is illustrated in Figure 17. After a segment has been 
routed to an incoming or outgoing group, the INHDR or OUTHDR macro deter- 
mines whether this is the first segment of a message, or a segment other than the 
first. Only the first segment of a message not having a multiple-buffer header is 
routed to the inheader or outheader subgroup (if present). All segments 
(including the first) are normally processed/ by the inbuffer or outbuffer sub- 
groups present in the group handling the message. The macros in the inheader, 
outheader, inbuffer, and outbuffer subgroups are executed on a segment-by- 
segment basis, while those in the inmessage and outmessage subgroups are not 
executed until the entire message has been handled by the other subgroups. The 
inmessage subgroup is executed when the last message segment reaches the 
inmessage delimiter. The outmessage subgroup is not executed until after the 
entire message has been transmitted to the destination station or sent to the 
appUcation program. 

In Figure 17 there are only three subgroups per group, and it is assumed that all 
the subgroups are involved in handling the message. Since some subgroups are 
optional, a group may have fewer than three subgroups, but a group may also have 
many more than three subgroups by including more than one subgroup of a given 
type. Moreover, not all subgroups included in a group need be involved when the 
group handles a particular message; TCAM provides selective execution of 
subgroups according to the setting of a path switch. This variable-processing 
capability is discussed later in this chapter. 
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Figure 17. Flow of a Two-Segment Message with a Single-Buffer Header through an MH 
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Multiple-Buffer Header Handling 

Figure 18 illustrates the flow through an MH assigned to a line group of a two- 
segment message having a multiple-buffer header. The main difference between 
this type of flow and that described above for a message not having a multiple- 
buffer header is the way in which the inheader and outheader subgroups are 
executed. 

The first segment of a message having a multiple-buffer header consists entirely of 
header information. This first segment does not go through the entire inheader or 
outheader subgroup. Once the. last field in this segment has been processed by 
field-dependent instructions in the inheader or outheader subgroup (once the scan 
pointer has advanced to the end of the buffer), TCAM saves the address of the 
next (unexecuted) inheader or outheader instruction and also saves the contents 
of all registers specified by the USEREG= operand of the INTRO macro. The 
first segment continues through the inheader or outheader subgroup, but only 
those macros that do not depend on the location of the scan pointer or upon 
certain data being in the buffer are executed for it. Among such macros are 
CHECKPT, CODE, COUNTER, LOCOPT, LOG, MSGFORM, MSGLIMIT, 
and TERRSET. The INITIATE, LOCK, MSGTYPE, PATH, SCREEN, 
SETEOF, and UNLOCK macros execute if the conchars operand is not coded for 
them. The FORWARD macro executes if the destination is specified in the macro, 
rather than in the message header. The PRIORITY macro executes if the priority 
level is specified in the macro and no conchars operand is coded. 
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not executed until after the entire message has been 
sent. 

Figure 18. Flow of a Two-Segment Message with a Multiple-buffer Header through an MH 
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In Figure 18, a dotted flow line through the inheader/outheader section indicates 
that the scan pointer has reached the end of the first header segment, and only 
those macros listed above are being executed for it. 

When the second segment is ready for handUng, STARTMH routes it directly to 
the inheader or outheader instruction whose address was saved, rather than to the 
INHDR or OUTHDR macro at the beginning of the subgroup. (At this time, 
TCAM also restores the contents of the registers specified by the USEREG= 
operand of the INTRO macro.) 

If the CODE, FORWARD, PRIORITY, or INITIATE macros are issued in an 
inheader subgroup handling multiple-buffer header segments, these macros must 
be specified early enough in the subgroup so that they act upon the first message 
segment. This also appUes to PATH macros issued in an inheader or outheader 
subgroup, if all segments of the message are to be handled alike. 

Note: Figure 18 contains only one of each kind of subgroup. For messages 
with multiple -buffer headers, the use of multiple inheader or outheader 
subgroups is severely restricted; all such subgroups must begin processing on 
the first message segment. In addition, if part of a multiple -buffer header is 
to be processed by an inheader subgroup and the rest is to be processed by 
an outheader subgroup, both subgroups must begin execution on the first 
message segment. 

The execution of an inheader or outheader subgroup can begin only on the first 
segment of a message. This is because the INHDR or OUTHDR macro for a 
particular inheader or outheader subgroup causes all message segments except the 
first to bypass the subgroup. One inheader or outheader subgroup can handle a 
multiple-buffer header because the INHDR or OUTHDR macro does not get the 
opportunity to check segments other than the first (due to the way in which 
multiple-buffer headers are handled). If a second inheader or outheader subgroup 
is coded to begin execution midway through the second segment, it will never 
execute; its INHDR or OUTHDR macro will route incoming segments directly to 
the next delimiter. 

Note: // an out buffer subgroup precedes an outheader subgroup that process- 
es more than one segment of a message having a multiple -buffer header, the 
out buffer subgroup is executed for the first segment only. 
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Note 1 : Will cross if conchars is not specified, or if entire character string 

is in a subsequent buffer. 
Note 2: Except that an operator command must be complete in a single 

buffer. 
Note 3: Will cross if destination is in the macro or an option field and 

the macro is executed for the first buffer. 
Note 4: Will cross but origin may not be known on dial lines for first 

buffer. 
Note 5: Will cross if conchars is not specified and priority level is in macro. 

Variable Processing Within a Message Handler 

The path of a message through a Message Handler may be varied dynamically 
using the PATH and MSGTYPE macro instructions. By permitting different 
operations upon different types of messages directed to the same Message Han- 
dler, these macros enhance the versatility of the Message Handler. By judiciously 
using PATH and MSGTYPE macros, the user can design one Message Handler 1 

that will handle messages having a variety of header formats and that will perform 
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different operations upon different types of messages, even when these different 
types are transmitted over the same Hne. Indeed, the user may in some cases be 
able to design a single Message Handler capable of processing all the messages 
that can be generated in a large TCAM-based telecommunications system per- 
forming a wide range of tasks. 

The path of a message through a Message Handler may be varied in two ways. 
One of these involves the use of control characters in the message header, and the 
other involves the setting of switches, based on the control characters, that 
determine whether a given subgroup is to be executed for the message. 

These switches, called path switches , are one-byte fields in the option table. The 
switches are initialized by an operand of the TERMINAL or TPROCESS macro 
and may subsequently be modified by a PATH macro or by a combination of 
OPTFIELD and DATOPFLD operator commands. An operand of a delimiter 
macro may specify that certain bits of a path switch are to be tested. If any of the 
specified bits are on, the subgroup introduced by the delimiter is executed; if none 
of the specified bits are on, control passes to the next subgroup. If a delimiter 
macro does not specify a path switch to be tested, its subgroup is executed uncon- 
ditionally. Different delimiters may test different sets of path switches. For an 
example of the use of path switches and the PATH macro to control the routing of 
messages from subgroup to subgroup, see the discussion of the PATH macro. 

By specifying, changing, and testing path switches, the user can determine which 
of the subgroups in an MH group are to be executed for a particular message. To 
control the path of a message within an inheader or outheader subgroup, the user 
may employ the MSGTYPE macro. The MSGTYPE macro compares a character 
or character string in the message header with a character or character string 
specified by a MSGTYPE operand. If the two characters or character strings 
match, the instructions between this MSGTYPE macro and the next MSGTYPE 
macro in the subgroup are executed (if this is the last MSGTYPE macro in the 
subgroup, all the remaining instructions in the subgroup are executed) and control 
is then passed to the next delimiter macro. If the two characters or character 
strings do not match, the instructions associated with this MSGTYPE macro are 
not executed, and control passes to the next MSGTYPE macro in this subgroup 
(or to the next delimiter, if this was the last MSGTYPE macro in the subgroup). 
A new comparison is made by each MSGTYPE macro to which control is passed. 
For an example of the use of the MSGTYPE macro to vary processing within a 
subgroup, see the description of the MSGTYPE macro. 

The PATH macro controls the routing of a message among subgroups. The 
MSGTYPE macro controls the path of a message within an inheader or outheader 
subgroup. 

Conditional Execution of Message Handler Functional Macros 

Several MH functional macro instructions may request conditional execution 
dependent upon the existence of a control field in the message. These macros are 
INITIATE, LOCK, MSGTYPE, PATH, PRIORITY, SCREEN, SETEOF, and 
UNLOCK, with the optional operand conchars. conchars may consist of from 
one to eight nonblank characters and may be specified in unf ramed character 
format or with framing C* ' or CLn' ' characters, or in hexadecimal format with 
framing X' ' or XLn' ' characters. 

These conditional characters specified in the macro are compared with the field in 
the message at the current location of the scan pointer. If the fields are identical. 
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the macro will be executed and the scan pointer will be advanced to the last 

character of the field. If the characters do not match, the scan pointer is not 

moved and the macro is not executed. If two or more macros in the same sub- ^ 

i 
group specify control character strings that are identical to a certain point but 

differ in length, and if there is any possibiHty that the same field in the message 

header will be checked for both strings, then these macros should be arranged 

according to decreasing length of their character strings. For example, if the user 

codes 

INITIATE 1 
LOCK 1 2 

in his inheader subgroup, both macros will execute if the field in the message 
header contains 112. However, if the field contains 12, only the INITIATE macro 
will execute. 

If the conditional characters are framed with CLn' ' or XLn' ' framing characters, 
n should agree with the actual count of characters. If n specifies a value greater 
than the actual count, it is possible that the macro may never be executed. For 
example, if a character string AB is defined as CL3*AB', the field is automatically 
padded to the right with a blank. If the BLANK = operand specifies 
BLANK=YES (or BLANK=X^40' or BLANK=C* '), a matching field can never 
be found. BLANK=YES states that blanks are not to be considered part of the 
character string when found in the header, but in this case the string used to 
determine execution contains a blank. 

In the case of multiple-buffer headers, the control characters must all be in the 
same buffer. The control characters may be entirely contained within the buffer I 

in which the scan pointer is located when the comparison is begun, or they may be % 
entirely contained within a subsequent buffer. They may not, however, be split 
between buffers. 

If the sequence 

MSGTYPE ABC 
MSGTYPE AB 
MSGTYPE A 

is coded by the user, and if the characters being checked are AB and these are the 
last two bytes in the buffer, the first MSGTYPE executes just as if three charac- 
ters were found but the compare was unequal. That is, the code following the first 
MSGTYPE is not executed and control passes to the second MSGTYPE macro. 
Execution of the second MSGTYPE finds two bytes, detects an equal compare, 
and passes control to the code following the second MSGTYPE. Note in this 
example that, even if a C is the next character beyond the AB in the message, the 
first MSGTYPE does not find the string because it is split between buffers. 

If the string ABC is the next string in the message and is located entirely within 
the next buffer, execution of the first MSGTYPE detects that no characters 
remain in the current buffer. Processing of buffer fields in this buffer is deferred, 
(including the subsequent MSGTYPE processing). When the next buffer is 
passed to the Message Handler, execution of the first MSGTYPE resumes at the 
start of data in this next buffer and, because the string ABC is found, control 
passes to the code following the first MSGTYPE macro. 
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It is likely that the first result, where the string is split between buffers, is not the 
result desired by the user. To avoid such a result, either limit the header to a 
single buffer or avoid strings that are partially identical. 

User Code In A Message Handler 

The user may insert serially reusable assembler or macro-language code in a 
Message Handler to supplement the facilities provided by TCAM. User-written 
code can be included as either an open or closed subroutine. 

There are several reasons why the user might include such a subroutine. There 
may be no MH macro to process particular information he wishes included in his 
message headers. He may wish to expand the scope of an MH macro (for exam- 
ple, to correct an invalid destination field detected by the FORWARD macro). 
Or, he may wish to process a header field in a manner entirely different from that 
in which the MH macro handles fields of this type, for example, inserting a date 
having a format different from the one used by the DATETIME macro. 

General Requirements and Restrictions 

The following requirements and restrictions apply to both open and closed user- 
written subroutines that supplement the functions provided by TCAM macros in a 
Message Handler. 

1. All such subroutines must be serially reusable. 

2. No executable code should be included within an inmessage or outmessage 
subgroup, or between such subgroups. 

3. Branching from one Message Handler to another is not permitted. 

4. System macros that issue an SVC should be avoided, unless the user is fully 
aware of the implications of using such macros in the TCAM system. 

5. If the user provides a field or work area (as for the ERRORMSG, MSGGEN, 
and MSGEDIT macros), the field must be addressable by the MH. Such a field 
is addressable if placed after the OUTEND macro. If only one base register is 
used to establish addressability for the MH, the field must also be within 4096 
bytes of the STARTMH macro in order to be addressable. 

6. Nothing should be done that rehnquishes control. 

7. TCAM macros cannot be used in a closed subroutine. 

Multiple 'Buffer Header Considerations 

When the MH is handling messages having multiple-buffer headers, user code 
within the inheader and outheader subgroups should test register 1 5 for a negative 
return code before executing any open user subroutine or branching to a closed 
user subroutine, if the user subroutine to be executed depends upon certain data 
being in the buffer or upon the location of the scan pointer. A negative return 
code indicates that the previous TCAM macro needed the next buffer but it was 
not available (for an understanding of how this situation could arise, see 
Multiple- Buffer Header Handling in this chapter). If a negative return code is 
detected, a branch should be made around a user subroutine that depends upon 
the presence of certain data in the header, or upon the scan pointer; such a 
subroutine is eventually executed on header fields in a subsequent message 
segment. 

The USEREG= operand of the INTRO macro specifies the number of registers to 
be saved between header segments when user code is executed in an inheader or 
outheader subgroup that may handle multiple-buffer headers. The registers saved 
are sequentially ordered, beginning with general register 2. When the scan pointer 
comes to the end of a message segment and there is still code to be executed in the 
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inheader or outheader subgroup processing the segment, TCAM saves the address 
of the next (unexecuted) inheader or outheader instruction and also saves the 
contents of the registers specified by USEREG = . The segment continues through 
the subgroup, but macros that depend upon the location of the scan pointer or 
upon specific data being present in header fields do not execute for the segment. 
When the second segment is ready for handling, the STARTMH macro routes it 
directly to the inheader or outheader instruction whose address was saved, and 
restores the contents of the saved registers. (See Multiple- Buffer Header 
Handling for more information on this topic.) Only the contents of those user 
registers specified by USEREG= are saved and restored. 

Use of the USEREG= operand increases the size of the MCP. This operand 
should be coded only when an inheader or outheader subgroup that contains user 
code can expect to handle messages having multiple-buffer headers, with the user 
subroutine extending across buffers. 

The user can determine the number of extra bytes of main storage that coding 
USEREG= will require by applying the following formula: 

S=4R(L+T) 

where 

S is the number of extra bytes added to the MCP. 

R is the number of registers to be saved between buffers, as specified in the 
USEREG= operand of the INTRO macro. 

L is the number of lines in the system on which are located stations whose 
TERMINAL macros omit the BFDELAY= operand. 

T is the number of stations whose TERMINAL macros specify the 
BFDELAY= operand. 

Under certain error conditions, TCAM sends buffers that contain no data through 
the MH to execute the proper inmessage or outmessage subgroup. These buffers 
should be handled accordingly by any user code that depends upon data being in 
the buffer or upon the location of the scan pointer. See Using SETS CAN to 
Locate a Header Field for specific considerations. 

Including an Open Subroutine 

A user-written open subroutine consisting of one or more assembler language or 
system macro instructions may be included in-Hne in the inheader, inbuffer, 
outheader, and outbuffer subgroups of a Message Handler. TCAM macros may 
be included in an open subroutine. All registers except register 12 and 13 are 
immediately available for use in such a subroutine. If register 13 is used in the 
subroutine, its original contents must be saved and restored by the user. Register 
12 should not be changed by user code, since it is the base register. If more than 
one base register is used, the other base registers must also be preserved. 

When a user-written open subroutine is coded in an inheader or outheader sub- 
group that can handle messages having multiple -buffer headers, the contents of 
user registers will be lost if the header fields being processed by the user routine 
extend across more than one buffer. (To see why this is so, consider carefully the 
Multiple-Buffer Header Handling in this chapter.) The user may specify that the 
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contents of his registers be preserved in this case by suitably coding the 
USEREG= operand of the INTRO macro. When this operand is coded, the 
; contents of the user's registers are saved when the scan pointer reaches the end of 

the first segment of a message having a multiple-buffer header, and are restored to 
the user routine when the second segment arrives at the inheader or outheader 
subgroup. 

Including a Closed Subroutine 

A user-written closed subroutine may be included as a control section in the MCP. 
Access may be gained to such a subroutine by any Message Handler in the MCP, 
or as a result of an exit being taken that is specified by an INTRO, STARTMH, 
DCB, READY, ERRORMSG, or FORWARD macro. A closed subroutine 
cannot contain TCAM macros except MHGET and MHPUT. When activating a 
closed subroutine, the user must provide his own linkages; he should save and 
restore the invoking Message Handler's registers. Figure 19 illustrates the flow of 
control between an MH and a user-written closed subroutine, and presents the 
recommended linkages. 
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MHl 



(Dafa Set initialization macros) 
STARTMH 



(Other MH macros) 



CALLUSERRTN>- 
• (Next MH Macro) 






(USERRTN calls no other subroutine) 
-^ USERRTN CSECT 

USING *,15 
SAVE (14,12) 



(User G)de) 



<RETURN (14,12),T 
END 









(USERRTN 


calls another subroutine) 




"^ USERRTN 


CSECT 

USING M5 

B SKIP 




SAVEl 


DC ISF'O' 




SKIP 


SAVE (14,12) 
ST 13,SAVEH-4 
[A 12, SAVEl 
ST 12,8(13) 
LR 13,12 
DROP 15 
USING SAVEl, 13 

• 
(User Code) 

• 
L 13,4(13) 

—< RETURN (14,1 2), T 










END 



Figure 19. Activation of a Closed, User-Written Subroutine 



< 



178 OS/MFT and OS/MVT TCAM Programmer's Guide 



Using LOCOPT To Locate An Option Field 

The LOCOPT macro enables the user to obtain the address of any option field 
assigned to a particular station. The address of the desired field is placed in a 
user-specified register. A user-written routine may then examine and modify the 
contents of the option field. 

Using SETSCAN to Locate a Header Field 

The SETSCAN macro may be used to locate a portion of the message header for 
subsequent examination or processing by a user-written subroutine (but see 
Restriction #5 in the section General Requirements and Restrictions,) For a 
detailed description of the capabilities of SETSCAN, see the discussion of the 
macro. 

Note: Error buffers that contain no data should be handled accordingly by 
user code that depends upon data being in the buffer or upon the position of 
the scan pointer. If using the SETSCAN macro to locate a field for pro- 
cessing by user code, the user should recognize a buffer with no data by 
testing for a return code of XTC in register 15. If the return code X'FC is 
in register 15, the user code that depends upon data being in the buffer or 
upon the position of the scan pointer should be bypassed. 

Two capabiHties of SETSCAN are of particular interest with respect to user code: 

• By coding MOVE = RETURN, the user may employ SETSCAN to locate a 
designated character string in the header and to place the absolute main-storage 
address of the last character of the string in a specified register, to be used by 

; user code. When MOVE=RETURN is specified, the scan pointer is not 

^ actually moved, so the user need not worry about repositioning it. If this 

capabiUty is to be utilized effectively, the character string to be examined must 
be located entirely within a single buffer unit, because buffer units are not 
usually contiguous in main storage; consequently a long character string may be 
split between two units in different locations in main storage. If the character 
string to be processed is divided between two buffer units, and the user knows 
where in the string the division occurs, he may treat the segments as separate 
character strings, issue a SETSCAN macro specifying MOVE = RETURN to 
find the address of each, and process each independently. 

• SETSCAN may be used to determine the main-storage address of the header 
byte to which the scan pointer is currently pointing. This is done by specifying 
MOVE = RETURN and coding as the integer operand. If the user codes 

SETSCAN , MOVE=RETURN 

the address of the current location of the scan pointer is returned in register 15. 

Using MSGTYPE To Locate A Header Field 

User-written code may be included in inheader and outheader subgroups to 
interrogate and modify a field in a buffer of a message, and to interrogate but not 
modify a field that spans more than one buffer of a message header. 

The next field in a buffer, the one immediately following the scan pointer, can be 
obtained from the buffer by using a MSGTYPE macro that dehberately fails as 
follows: 
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MSGTYPE C ' XXXXXXXX ' 
MSGTYPE 

Access to fields up to eight bytes in length can be gained by this method, the 
number of characters in the MSGTYPE operand is the length of the field. In this 
example, an eight-byte field is to be located. Care should be taken not to specify 
as the MSGTYPE operand any string that could be found in the header. If a 
matching string is found, the scan pointer is adjusted to point to its last byte. 

If the string sought extends across buffers, it cannot be modified. This can be 
determined by examining the contents of the second byte of the AVT parameter 
area lEDPARM, addressable throughout the MCP. If this byte is less than the 
requested length, the field spans buffers. The byte at lEDPARM+l is maintained 
in hexadecimal format. 

If the field does not span buffers, it may be modified by the use of the MSGEDIT 
macro. Insertions before the string, removal of the string, or removal and replace- 
ment of the string may be performed by coding an appropriate MSGEDIT macro 
with the AT operand specified as SCAN (see the discussion of the MSGEDIT 
macro in this chapter). Insertion after the string may be performed by coding a 
SETSCAN macro with a count equal to the length of the string, followed by the 
desired MSGEDIT macro. It is recommended that a MSGEDIT macro specifying 
the string itself as the AT operand not be used, since all occurrences of the string 
found, not merely the first one, will cause the MSGEDIT function to be per- 
formed. 



The following procedure allows the examination of a field that begins in one 
buffer and ends in a subsequent buffer (not necessarily the next buffer). It makes 
use of two parameters returned by the MSGTYPE function: ^ 

1. The characters found, whether matching or not, and whether as many as i 
requested or not, are placed in the AVT work area lEDDOUBL; 

2. The count of characters found is placed in the second byte of the AVT parame- 
ter area lEDPARM. 

The procedure may be varied depending on the length of the field to be examined. 
This example assumes the maximum, an eight-byte field. 



SPLIT 



LOOP 



SET INITIAL LENGTH DESIRED 
POINT TO EIRST BYTE 
OE WORK AREA 



TEST IF ANY BYTES FOUND 
BRANCH IF NOT TO AWAIT 
NEXT BER 

The operand of the MSGTYPE macro should specify the same number of characters 
as in the string desired, and the operand should be such that a match cannot be 
found. Because no match is found, the MSGTYPE macro branches to the next 
delimiter. Therefore, a delimiter must be specified as a branch address. In this case, 
MSGTYPE is used. 



MVI 


COUNT, 8 


LA 


RWORK,WORK 


CNOP 


0,4 


MSGTYPE 


C XXXXXXXX' 


MSGTYPE 




CLI 


IEDPARM+1 ,0 


BE 


NEXT 



SR 


REGA,REGA 


CLEAR REGISTER FOR 
INSERT 


IC 


REGA, COUNT 


PICK UP DESIRED 
COUNT DECREMENT 


BCTR 


REGA,0 


FOR EXECUTE 


EX 


REGA , MOVE 


MOVE BYTES FOUND 
TO WORKAREA 



i 
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LA 



CLC 

BE 



REGA, KREGA) 



RESTORE TRUE 
DESIRED COUNT 



These instructions move the characters found to the work area. The MVC 
instruction (MOVE) is executed by the EX instruction so that the target 
address of the MVC can be modified. 



C0UNT,IEDPARM+1 



FOUND 



ARE ALL DESIRED 
BYTES FOUND 
BRANCH IF YES 



The count field will be higher if not all the bytes are found. 



SR 
IC 
AR 



SR 



STC 



SCAN 

) 

* 

MOVE 
WORK 
COUNT 

FOUND 



STC 

SETSCAN 

B 



MVC 

DS 

EQU 



DS 



REGB,REGB 
REGB,IEDPARM+1 
RWORK , REGB 



CLEAR REGISTER 
FOR INSERT 
PICK UP NUMBER 
OF BYTES FOUND 
ADJUST WORK AREA 
ADDRESS 



The address register for the work area now points to the next byte to be 
filled, which will come from a subsequent buffer. 



REGA,REGB 


COMPUTE HOW 




MANY MORE 




BYTES NEEDED 


REGA, COUNT 


AND RESET 




LENGTH FIELD 


REGA,SCAN+7 


MODIFY SETSCAN 





PARAMETER LIST 


LOOP 


GO GET REMAINING 




BYTES 


0( 0,RWORK),IEDDOUBL 


EXECUTED MOVE 


CL8 


INSTRUCTION 


LOOP+ 1 1 




OH 


EXAMINE FIELD IN 




WORK 



The SETSCAN function moves the scan pointer to point to the last byte in the 
buffer. The skip length is adjusted to the proper number by modifying the parame- 
ter list. 

When the MSGTYPE function is executed again, the scan pointer is moved 
beyond the end of data in the buffer. The test following MSGTYPE must branch 
back to the next required buffer processing. Because of the setting of the scan 
pointer, that processing will not be performed on this buffer. 

When the next buffer is passed to the Message Handler, execution of the 
MSGTYPE function will be started again. At this time, the remaining bytes 
desired will usually be obtained. 

Note, however, that if the next buffer does not contain enough bytes to complete 
the count desired — if, for example, it contained only blanks — the buffer following 
it would be examined. That is, the field desired may actually be split over many 
buffers, and the procedure will still continue. 



Designing the Message Handler 181 



Using the FARM Parameter of the EXEC Job Control Statement 

The user may wish to pass information to his user code by means of the FARM 
parameter of the EXEC job control statement (this capability is described in the 
OS publication Job Control Language . If the PAR1VI= operand is specified, 
when control is passed to TCAM register ! contains the address of a fullword, the 
low-order three bytes of which contain the address of a two-byte length field 
immediately followed by the data specified in the FARM parameter. INTRO 
stores the contents of register 1 in a fullword on a fullword boundary, from which 
it may be retrieved by user code. The name of the fullword is lEDSPLPT. The 
address in register 1 is then overlaid. 

Message-Handler Macro Return Codes 

During execution, certain MH macros cause a return code to be placed in a 
general register, usually register 15. The table below lists those TCAM macros 
whose return codes may be checked by user code in a Message Handler. The 
return code occupies the low-order byte in the register indicated; the rest of the 
register usually contains all zeros. Return codes of X'FC are negative return 
codes; the high-order three bytes of the register contain binary ones. Some 
macros also return an address in a register; the locations and nature of such 
addresses are also indicated in the following table. 







Return 


Macro 


Register 


Code 


COMMBUF 


15 


X'OO' 




15 


X'04' 



15 



15 



X'08' 



X'OC 



Meaning 

Good return 

Data area too small; macro did not 

execute. (The data area 

size specified in the COMMBUF= 

operand of the INTRO macro is 

too small). 

MAXDEEP value exceeded. 

(register 1 will contain the 

number of times MAXDEEP was 

exceeded). 

LIST= operand specified 

a name which was not 

a TLIST entry. 



I 



COUNTER 


15 


X'OO' 


Good return 




15 


X'FF' 


Option field not found 


CTBFORM 


15 


X'04' 


Separator character insertion 
requested; none defined. 




15 


X'08' 


Insertion of opfield data 
requested; option field not 
found. 




15 


X'OC 


Combination of X'04' and 
X'08'. 




15 


X'lO' 


Insertion of device id requested; 
device id not defined. 




15 


X'14' 


Combination of X'04' and X'lO 




15 


X'18' 


Combination of X'08' and X'lO 




15 


X'lC 


Combination of X'04', X'08', 
and X'lO' 



( 
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15 



X'20' Requested insertion of device 

id and option field; not done 
(out of units). 



DATETIME 


15 


X'OO' 


Good return 




15 


X'04' 


Insufficient reserve characters 


FORWARD 


15 


X'OO' 


Good return 




15 


X'04' 


Invalid destination 


LOCK 


15 


X'OO' 


Good return 




15 


X'04' 


Destination not specified 




15 


X'08' 


Destination not a process entry 


LOCOPT 








a) if return 


15 


Address 


Good return 


requested in 




of 




R15 




option 
field. 






15 


X'OO' 


Option field not found 


b) if return 


15 


X'OO' 




requested 


USEREG 


Address 


Good return 


in user- 




of 




specified 




option 




register 




field. 




(USEREG) 


15 


X'04' 






USEREG 


Un- 
changed 


Option field not found 


LOG 


15 


X'OO' 


Good return 




15 


X'04' 


DCB or LOGTYPE entry named 
in macro not found 


MHGET 


15 


X'OO' 


MHGET successful; no errors. 




15 


X'04' 


Data moved; work area too 
small; data truncated. 




15 


X'08' 


TCAM not in system. 




15 


X'OC' 


Empty buffer; no user processing 
permitted. 


MHPUT 


15 


X'OO' 


MHPUT successful. 




15 


X'04' 


MHPUT could not allocate enoug 



15 


X'08' 


15 


X'lO' 


15 


X'OC 



units; data is truncated. 

This return code is also 

set when the number of 

units per buffer has 

reached maximum. 

TCAM not in the system. 

Length of work area not initialized. 

Reserves specified are too large; 

data was moved. 
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Macro 
MSGEDIT 



Register 

15 
15 



Return 
Code 

X'OO' 
X'04' 



Meaning 

Good return 

No units available 



MSGLIMIT 15 

15 



ORIGIN 



15 
15 

15 

15 



QACTION 


15 


SCREEN 


15 


(2260) 


15 




15 


SCREEN 


15 


(3270) 


15 




15 




15 



X'OO' Good return 

X*04' Option field not found 

X^OO' Good return. The ORIGIN macro 

executed successfully. 

X'04' Invalid origin. The FORM= operand 

was specified and the source 
terminal was not valid. 

X*08' The FORM= operand was specified, 

but the source terminal is not 
in the concentrator network. 

X*OC' The FORM= operand was specified, 

but the origin specified in the 
message is not a valid name or ID 
for a terminal attached to the 
concentrator entering d^ta (the 
first terminal entry following 
the entry for the concentrator 
is assumed to be the origin). 

X'08' No buffers available. 

X'OO' Function not done. 

Function Good return 

Byte 

X*04' Invalid operation for 2260 

X*00' Function done. 

X'04' Invalid operation for 3270. 

X'08' Invalid buffer data stream. 

X'OC Command code not found or 

invalid use of EAU, WDC, or 

WRE. 



SEQUENCE 




a) macro 


15 


issued in 


15 


inheader 


15 


subgroup 


15 


b) macro 


15 


issued in 


15 


outheader 




subgroup 




SETEOM 


15 




15 




15 



X^OO' 
X^04' 
X^OS' 

X'OO' 
X'04' 



X'04' 
X'OS' 
X'OC 



Good return 

Sequence number in message high 

Sequence number in message low 

Originating station unknown 

Good return 

Insufficient reserve characters 



EOM delimiter used 
Delimited by user-specified length 
Delimited by EOM and user- 
specified length 



i 
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Macro 

SETSCAN 

al) locate 

specified 

character 

string 

and return 

address in 

R15 

a2) locate 
specified 
character 
string 
and return 
address 
in user- 
specified 
register 
(USEREG) 



bl) skip 

n characters 

and return 

address 

inR15 



b2) skip 
n characters 
and return 
address 
in 

user- 
specified 
register 
(USEREG) 

c) skip 

n characters 

backward 



d) locate 
scan pointer 
address 



TGOTO 



Register 
15 

15 
15 
15 
USEREG 



15 
USEREG 

15 
USEREG 



15 



15 



15 
USEREG 



15 
USEREG 



15 
15 



15 

15 
15 



Return 
Code 



Address 
of last 
character 
in string. 
X'OO' 

XTC 

X'OO' 

Address 
of last 
character 
in string 
X'04' 
Un- 

changed 
XTC 
Un- 
changed) 

Address 
of 

character 
skipped to 
X'OO' 



X'OO' 
Address 
of 

character 
skipped 
to 

X'04' 
Un- 
changed 

X'OO' 
X'04' 



Address 
of scan 
pointer 
X'FC 

X'04' 



Meaning 



Good return 



Specified character string not 

found in this buffer 

Scan pointer beyond end of buffer. 

Good return 



Specified character string 
not found in this buffer 

Scan pointer beyond end of buffer. 



Good return 



n greater than the number of 
characters remaining in this buffer 



Good return 



n greater than the number of 
characters remaining in this 
buffer 

Good return 

n greater than the number of 
characters preceding the scan 
pointer in this buffer 

Good return 



Scan pointer beyond end of buffer. 

The terminal that entered this 
message either is not attached to a 
concentrator, or is attached but the 
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Message Translation 



station's TERMINAL macro does 
specify LMD=YES or MB=YES. Pro- 
cessing continued in the inmessage 
subgroup of the first MH. 

15 X'08 ' The TGOTO macro specified that the 

name of the second MH for the 
terminal entering the message was 
in an option field, but the option 
field was not initiaUzed by the 
OPDATA= operand of the station's 
TERMINAL macro. 

1 5 X'OC The address of the second MH, 

specified either in the TGOTO 
macro or in an option field, 
is not a valid MH address. 

Note: All macros give an error return code if a zero-length buffer 
(see Glossary) is passed through the message handler. 



TCAM provides a facihty for translating incoming messages from Une code into 
EBCDIC and for translating outgoing messages from EBCDIC to line code. 
Translation is specified by issuing a CODE macro in the incoming and outgoing 
groups of an MH. 

The user who does any appreciable amount of header analysis, or whose system 
includes stations using different Hne codes, will probably want to use TCAM's ^ 

translation facility. Incoming translation must be specified for lines over which ^ 
operator commands may be entered, since the CODE macro is used by TCAM to 
check for such messages (see the discussion of the CODE macro for a way of 
selectively translating operator commands while leaving other messages entered 
on the same hne untranslated). 

Translation is not required in a message-switching application for which httle or 
no header analysis is required, provided that the originating and destination 
stations are of the same type. The careful user may be able to avoid translating in 
other situations. The operands of most MH macros may be specified in hexadeci- 
mal format. By using the tables and information located in Appendix G , the user 
may enter in his MH macro operands the hexadecimal representation of header 
fields that are in line code and thereby avoid having to translate. The user seeking 
to avoid translation should remember that the names entered in the terminal table 
(that is, the names given to the TERMINAL, TLIST, TPROCESS and LOGTYPE 
macros) must be specified in EBCDIC characters; no hexadecimal capabihty is 
provided for specifying these names. 

The user may avoid translation of messages handled by a particular incoming or 
outgoing group of a Message Handler by omitting the CODE macro from that 
group. The user may avoid translation of messages received from or sent to the 
Hues in a certain Une group by coding a CODE macro having no operand and by 
specifying TRANS =EBCD in the line group DCB macro for the Une group. 



Translation is usually accompUshed by using tables provided by TCAM, although 
the user may provide his own translation tables if he wishes. The user providing 
his own tables should format the individual 256-byte tables as described in the 



i 
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example illustrating the use of the TRANSLATE instruction in the OS publication 
Principles of Operation . A user-defined translation table should consist of a 
, fullword on a fullword boundary, followed by a 256-byte table for translating 

from Une code to EBCDIC, which is followed in turn by a 256-byte table for 
translating from EBCDIC to line code. The initial word should contain the 
address of the first byte of the second table. The control section containing the 
user-written translation table must be included at link edit time for the MCP. 

Translation tables are provided for all stations supported by TCAM. The names 
of these tables are given in the following list. When one of these names, or the 
name of a user-specified table, is coded as part of the TRANS = operand of the 
line group DCB macro, incoming messages for this hne group are translated from 
the specified line code to EBCDIC; outgoing messages are translated from 
EBCDIC to the line code, when CODE macros are executed in the incoming and 
outgoing groups of the MH for the line group. The table specified by the DCB 
operand can be changed for messages to or from a particular line, station, or 
application program by entering a different table name in the tablename operand 
of the CODE macro and by using MSGTYPE macros or path switches to cause 
different CODE macros to be executed for different messages (see Variable 
Processing within a Message Handler in this chapter). 

All of the characters in the character sets of each of the types of station supported 
by TCAM can be represented within the computer. However, some characters 
valid for one type of station may not be valid for another type, and some charac- 
ters valid for a station may have no EBCDIC equivalents. The way in which 
TCAM handles these problems is described in the sections Nonequivalent 
Characters and Substitutions in Appendix D. Internal and Transmission code 
^ Charts . 

►■' 

See Appendix G. Device- Dependent Considerations , for specific information 
about the character sets for the: 

• 1050 Data Communication System; 

• 2260 Display System; 

• 2740 Communications Terminal; 

• TWX stations; 

• WTTA terminals. 

Names of Code Translation Tables Provided by TCAM 

Table Name Type of Conversion Terminal 

1030 1030 code to EBCDIC and back IBM 1030 

1050 1050 code to EBCDIC and back IBM 1 050 

105F 1050 code to EBCDIC and back; IBM 1050 

converts incoming lowercase 
letters to uppercase 

1 060 1 060 code to EBCDIC and back IBM 1 060 

2260 2260 code to EBCDIC and back IBM 2260 

2265 2265 code to EBCDIC and back IBM 2265 

2740 2740 code to EBCDIC and back IBM 2740 
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Table Name 
274F 

BC41 
EB41 
CR41 

ITA2 

ZSC3 



Type of Conversion 

21 AQ code to EBCDIC and back; 
converts incoming lowercase 
letters to uppercase 

2741 BCD to EBCDIC and back 

2741 EBCDIC to EBCDIC and back 

2741 Correspondence Code to EBCDIC 
and back 

5-level International Telegraph 
Alphabet No. 2 to EBCDIC and back 

5-level Figure Protected Code 
ZSC3 to EBCDIC and back 



Terminal 
IBM 2740 

IBM 2741 
IBM 2741 
IBM 2741 

WTTA 

WTTA 



TTYA 



TTYB 



TTYC 



6BIT 
ASCI 



EBCD 



5-level (Baudot) code to EBCDIC 


AT&T 


and back 


83B3, 




WU115A 


8-level TWX code to EBCDIC and back 


AT&T 




33/35 




TWX 




(parity) 

AT&T ^ 


8-level TWX code to EBCDIC and back 




33/35 




TWX 




(non- 




parity) 


6-bit Transcode to EBCDIC and back 


IBM 2780 


ASCII to EBCDIC and back 


IBM 2770, 




2780, 3270, 




3670,3735, 




S/360, Model 20 


No translation; coded for stations 


IBM 1130, 


using EBCDIC transmission code, 


2770, 2780, 


and when no translation is 


2790, 3270, 


desired. 


3670,3735, 




3780, S/360, 




Model 20 



i 
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Using TCAM's Hold/Release Facility to Protect Outgoing Messages from Loss 

TCAM can temporarily suspend transmission of outgoing messages to a station. 
Transmission may be suspended either for a specified period of time or until the 
user chooses to resume outgoing traffic. Messages may be held either by the 
HOLD macro or by the operator command SUSPXMIT, and released by the 
RESMXMIT operator command, by the MRELEASE macro issued in an applica- 
tion program, or automatically at the expiration of the time interval specified by 
the HOLD macro. 

HOLD maybe used to defer transmission of messages that should not be sent 
immediately because of error conditions at the destination station (the destination 
is the station for the message being processed by the outmessage subgroup when 
HOLD executes). If the macro is not used, messages that cannot be transmitted 
because the destination is temporarily out of order are treated as if they have been 
transmitted, even though they do not reach their destinations. 

Once HOLD executes in an outmessage subgroup, no messages are sent to the 
destination station either until the interval specified as an operand of the macro 
expires, or until a RESMXMIT operator command or an MRELEASE application 
program macro is issued. Accumulated messages can be released by RESMXMIT 
or MRELEASE even though the specified time interval has not elapsed. 

HOLD can be either unconditional or conditional based upon the setting of the 
message error record. HOLD until a release is issued can be used if a station 
unexpectedly fails. The error situation might be detected by a HOLD macro 
based on the message error record. The interval format can be used if a station in 
1) the system is scheduled for maintenance for a specific period of time. In this case, 

an unconditional HOLD with the INTVL= operand might be used. 

The HOLD macro cannot be executed for a station supported by main-storage- 
only queues or for a station whose line is not open or has been opened idle. The 
operator command SUSPXMIT, which also causes an intercept, cannot be used 
unless a HOLD macro has been coded somewhere in the Message Handlers. If 
the operator control hold facility alone is required, the HOLD macro coded in an 
MH can specify an impossible combination of errors in the mask associated with 
the message error record. This will ensure that the macro is never executed and 
will provide the operator control capability. 

In addition to its function of protecting outgoing messages from loss, HOLD also 
may be used to achieve an inquiry/response capability, which is discussed in 
TCAM 's Inquiry /Response Facilities in the section Writing TCAM-Compatible 
Application Programs . 

Coding the Message Handler for an Application Program 

The user may code a special Message Handler for his application program, or he 
may include subgroups for his application program in an MH assigned to a line 
group. In the latter case, he must use variable routing through the MH, as dis- 
cussed in this chapter, to ensure that the application-program-related subgroups 
are executed only for messages being sent to or received from an application 
program. The PCB macro for an application program specifies the MH that 
handles messages to or from that application program. 
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Design Steps 



Do not code an outmessage subgroup in an MH handling messages destined for an 
application program; functional macros that appear in such a subgroup do not 
execute. An OUTMSG delimiter macro is not necessary since the OUTEND | 

macro provides any required TCAM functions in the absence of OUTMSG. 

If any messages are to be entered by the application program an incoming group is 
required. The incoming group must contain a FORWARD macro. 

The following MH functional macros should not be coded in subgroups handling 
messages being sent to or received from an application program: CUTOFF, 
LOCK, UNLOCK, MSGFORM, MSGGEN, MSGLIMIT, INITIATE, and 
SCREEN. 



The design of a Message Handler and related control areas is complex because of 
the large number of functions available in TCAM and the variety of requirements 
of different installations. The following general outline suggests a possible 
approach. 

1 . Define the requirements of the application. Are messages to contain both 
header and text segments? Is an application program involved? How many 
characters will be in a normal message and in the longest message? Optimum 
buffer size depends on this. 

2. Refer to the table of MH functions and macros defining the functions in a 
previous section of this chapter and the related text to determine which func- 
tional macro instructions might be used in the application. Study the detailed 
descriptions of these macros. Tentatively select those macros that provide the 

desired functions. # 

3. Design the message header, if applicable. Are the following fields % 
necessary — origin, date, time, destination (single or multiple), priority? Should 
the field be entered by the terminal operator or inserted by the Message Han- 
dler? What should the program EOA characters be? 

4. Start from a minimum Message Handler (required delimiter macros) and add 
the macros necessary to process the header. 

5. Determine what validity checking is required and add the appropriate macro 
instructions. 

6. Determine what error conditions need to be tested for and handled. 

7. Determine what supplementary functions are desired — logging, initiate han- 
dling, message limit, etc. 

8. Assemble the completed MCP and take a look at it before linkage editing. 

No attempt should be made to write a Message Control Program in one step. A 
program should first be written, assembled, and tested that provides a very few of 
the desired functions. Other functions may be added as famiharity with the 
TCAM facilities grows and as the simpler programs are run successfully. For 
example, in a message switching application, a first program might include only 
the delimiter macros and the ORIGIN, SEQUENCE, CODE, and FORWARD 
functions. A second step might add the block checking function of the 
STARTMH macro, DATETIME, and some ERRORMSG functions. A third step 
might add multiple destinations, message counting and logging, and additional 
error handling. A final step could add the MSGTYPE or PATH functions to 
handle different message types. 

The order in which macro instructions are specified requires thoughtful planning, g 
It is important that some macro instructions be specified early enough in a sub- ^ 
group so that they act on the first header buffer; these macro instructions are 
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CODE, FORWARD, PRIORITY, and INITIATE (and PATH if all segments of 
the message are to be handled alike). In determining the relative placement of 
macros within the subgroup, the use of the scan pointer must be understood. 
(Note the sample Message Control Programs in the chapter Putting the MCP 
Together .) 

Delimiter Macro Instructions 

Delimiter macro instructions identify the beginning or the end of various groups 
and subgroups of a Message Handler. They also provide initiahzation 
(addressability) and control functions within an MH. In the table below are the 
various groups and subgroups and the delimiter macro instructions that control 
their execution. 

The STARTMH macro identifies the beginning of an MH and must be the first 
instruction in every MH. TCAM provides initiahzation by setting up base regis- 
ters and addresses for an MH at this point. STARTMH code determines whether 
the message being processed is incoming or outgoing and directs the segment to 
the incoming or outgoing group accordingly. STARTMH handles end-of-block 
checking, if specified. 

STARTMH is the only delimiter macro that is always required. If the MH is to 
handle incoming messages, the INHDR, INEND, and OUTEND delimiter macros 
are required. If the MH is to handle outgoing messages, the OUTEND macro is 
required. Each of the remaining delimiters is required only if the user chooses to 
include in the MH the functional macros associated with that delimiter. 

If an incoming group is present, an inheader subgroup (or an inblock subgroup 
followed by an inheader subgroup) must be the first subgroup. An outheader 
subgroup may be specified before or after an outbuffer subgroup (if both are 
present). INEND and OUTEND identify the ends of the incoming and outgoing 
groups respectively. 

If an MCP contains more than one MH, a LTORG instruction (described in the 
OS pubUcation Assembler Language) should be coded immediately after the last 
delimiter macro (INEND or OUTEND) of each MH if in-Une user code includes 
literals. 
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MH Groups, Subgroups, and Delimiter Macro Instructions 



Message Handler 


Group 


Subgroup 


Delimiter Macro 






STARTMH 






INCOMING 
GROUP 


INBLOCK 
SUBGROUP 


INBLOCK 




INHEADER 
SUBGROUP 


INHDR 


INBUFFER 
SUBGROUP 


INBUF 


INMESSAGE 
SUBGROUP 


INMSG 






INEND 










OUTGOING 
GROUP 


OUTHEADER 
SUBGROUP 


OUTHDR 




OUTBUFFER 
SUBGROUP 


OUTBUF 


OUTMESSAGE 
SUBGROUP 


OUTMSG 






OUTEND 
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STARTMH 



The STARTMH macro 

• establishes addressability for an MH; 

• directs messages to an incoming or outgoing group, as appropriate; 

• specifies whether logical messages are defined; 

• specifies whether line-control characters are to be left in messages; 

• checks for occurrence of hardware errors during message transmission; 

• handles user-detected logical errors; 

• specifies whether tete-a-tete interaction may occur between the computer and a 
station; 

• specifies whether end-of-block completion handling is to be used; 

• is required as the first macro in every MH. 

STARTMH is required and must be the first macro instruction of every MH. This 
macro causes EOB checking to be performed. If a recoverable error is detected 
and no part of the block has been sent through the MH, retries are performed for 
receive operations (regardless of what STARTMH operands may specify). How- 
ever, if part of the block has been sent through the MH when a recoverable error 
is detected, EOB checking requires that the STOP=, CONT=, CONV=, or 
LOGICAL= operand be specified. Basically, this checking consists of determin- 
ing whenever an EOB, ETB, ETX, or EOT control character is received, whether 
certain types of transmission and user-specified logical errors have occurred; if so, 
the message is disposed of according to certain operands specified in STARTMH. 

For an incoming message, EOB checking occurs before a buffer containing an 
EOB is processed by the MH. If a hardware error is detected and retry is possible, 
a retry operation is performed (see the Glossary for a definition of retry). No 
message handUng occurs until the block is received again. If retry is not possible 
(because, for instance, the retry count is exhausted), either the error is ignored 
and the channel program is restarted to receive the next block, or transmission is 
terminated and the buffer continues through the MH, which processes it as the 
last buffer of the message. 

A buffer containing an incoming message segment is passed to the appropriate 
subgroup after EOB checking (if any), and when it is full. Depending upon how 
the user has coded the PCI= operand of the Une group DCB macro, and upon 
whether or not his incoming message contains EOB, ETB, or ETX control charac- 
ters, the buffer may be deallocated and passed to the appropriate MH subgroup 
soon after it is filled, or it may not be passed to the appropriate subgroup until 
transmission has ceased on the line; the latter case assumes there were no control 
characters in the incoming message. (See Dynamic and Static Buffer Allocation 
in the chapter Defining Buffers ). A full buffer is deallocated whenever a 
program-controlled interruption occurs; if PCI=N is specified, deallocation occurs 
when an EOB, ETB, or ETX control character is received (if there are no such 
characters, deallocation of buffers occurs after the transmission is completed). 

For outgoing messages, EOB checking (if specified) is performed after each block 
is transmitted. No check is made for logical errors. The transmission of a particu- 
lar block is deemed successful if the receiving terminal acknowledges that it has 
successfully received the block. Transmission errors detected by the terminal 
result in retries. Once the retry count is exhausted, transmission is either termi- 
nated or allowed to continue, as for incoming messages. After transmission has 
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terminated, control passes to the outmessage subgroup, whose macros may then 
check the message error record for the message and take appropriate action. 

See Appendix G. Device-Dependent Considerations , for specific coding informa- 
tion concerning the 1030 Data Collection System, the 1060 Data Communication 
System, the 2770 Data Communication System, and the 2780 Data Transmission 
Terminal. 



If the user specifies dynamic buffer deallocation by the PCI= operand of the line 
group DCB macro, and if the block size for his incoming messages is greater than 
his buffer size for incoming messages, segments containing transmission errors 
may be processed by the inheader and inbuffer subgroups of the MH before the 
EOB-checking routine detects the errors. Jn this case, when the EOB-checking 
routine detects the errors, segments in this block that have been enqueued are 
dequeued or ignored, and the input sequence number is decremented if it was 
incremented by a canceled segment. Dequeuing and sequence-number adjustment 
are done automatically by TCAM. However, any option fields that were updated 
on the basis of data in the canceled segments remain updated, and if the canceled 
segments were logged they remain on the logging medium. 

When the INITIATE macro is executed in the inheader subgroup handUng an 
incoming message, EOB checking is performed for that message, but there are no 
retries on the receive side (TCAM assumes an EOT condition when an error is 
detected on the receive side). 



Name 



Operation 



Operand 



mhname 



STARTMH 



LC= JOUTJ 

"(stop ] (YES 

_(cONt) ((opfield.switch) 

(YES 
,CONV=<' (opfield,switch) \ 
I NO 

,LOGICAL= \ (opfield) 

1 (opfieldl ,switch,opfield2) 

3REG= { integer [ 



,LMD= rVES 

^ (opfield,switch) 
( NO 



mhname 



Function: Name of the macro and of the Message Handler. 

Default: None. This name must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 
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LC= jIN \ 
|0UTj 



STOP= (yes 



I (opfield,switch) 



Notes: Must be the same as mhname specified in the MH= operand of the DCB 
for the Une group that uses this Message Handler. 



Function: Specifies whether Une-control characters in a start-stop message or in a 
BSC message in nontransparent mode are to be removed. 
Default: None. This operand must be specified. 
Format: IN or OUT. 

Notes: OUT causes TCAM to remove EOA and EOB Hne-control characters 
from incoming messages entered at a start-stop station, and to remove STX, ETX, 
SOH, and ETB Une-control characters from incoming messages entered at a BSC 
station. EOT Une-control characters are not removed when OUT is specified. 
EOB and ETB line-control characters are not removed when CONV=YES is 
specified, regardless of how LC= is coded. Line-control characters are not 
removed until after the message segment is in a buffer; therefore, the buffer must 
be large enough to accomodate Une control. 

The ITB control character is not considered by TCAM to be a line-control 
character and is not removed when OUT is specified. 

IN causes the line control to remain in incoming messages (unless such messages 
are in transparent mode, in which case "real" Une-control characters are removed 
regardless of how this operand is coded). 



Function: When a message block is found to be in error, this operand 
(conditionally) specifies that once the retry count is exhausted, transmission of 
this message is to be terminated. The error may be a hardware error or may be a 
user-detected logical error if the LOGICAL= operand is also specified. 
Default: None. Specification optional. 

Format: YES or (opfield,switch). op field must conform to the rules for assem- 
bler language symbols, and must be the name of a one-byte option field defined 
by an OPTION macro, switch may be either decimal or hexadecimal. If hexade- 
cimal format is used, framing X' ' characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that transmission is to be terminated unconditionaUy. 
(opfield^switch) specifies that transmission is to be terminated if any of the bits on 
in the switch are also on in the option field. 

When transmission is terminated because of an error detected by EOB checking, 
that portion of the message that has been received (or sent) continues through the 
incoming (or outgoing) group of the MH, where it is treated as if it were a com- 
plete message. The user may issue certain error-handling macros in the inmessage 
(or outmessage) subgroup of the MH that test bit 25 of the message error record 
and dispose of the message according to his specifications if bit 25 (which indi- 
cates that an error occurred during transmission of data) is on. If this operand is 
omitted, end-of -block checking is not done. 
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CONT= 



^YES ) 

] (opfield,switch) ) 



CONV= ( YES 

< (opfield,switch) 
(NO 



Function: When a message block is found to be in error, this operand 
(conditionally) specifies that once the retry count is exhausted, transmission of 
this message is to be continued. 
Default: None. Specification optional. 

Format: YES or (opfield,switch). opfield must conform to the rules for assem- 
bler language symbols, and must be the name of a one-byte option field defined 
by an OPTION macro, switch may be either decimal or hexadecimal. If hexade- 
cimal format is used, framing X* * characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that transmission is to continue unconditionally. 
(opfieldySwitch) specifies that transmission is to continue if any of the bits on in 
the switch are also on in the option field. 

When an error occurs, a bit in the message error record is set on. Message seg- 
ments are sent to the appropriate MH group as if no EOB error had been found. 
If this operand is omitted, end-of-block checking is not done. 



Function: Specifies whether EOB completion handling is to be used for the 
station, and (in conjunction with a LOCK macro) whether tete-a-tete interaction 
is in effect for the station. 
Default: CONV=NO 

Format: YES or NO or (opfield,switch). opfield must conform to the rules for \ 
assembler language symbols, and must be the name of a one-byte option field 
defined by an OPTION macro, switch may be either decimal or hexadecimal. If 
hexadecimal format is used, framing X' ' characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that tete-a-tete interaction is to be used unconditionally, 
and that a logical block of data being entered by a station is to be treated by 
TCAM as if it were a complete message. 

NO specifies that tete-a-tete interaction and EOB-completion handling are not to 
be used. 

(opfield.switch) specifies that tete-a-tete interaction and EOB-completion handling 
are to be used if any of the bits on in the switch are also on in the option field. If 
the path-switch setting is to be changed for this message, the first buffer must not 
contain an EOB if a change in EOB-completion handhng is desired for this 
message. If an EOB appears in the first buffer of this message, the next message 
will be the first message affected by the change. 

If the CONV= operand is specified, STOP= or CONT= must also be specified. 
If LMD= is coded with the (opfield, switch) option, CONV= can not use the 
(opfield,switch) option. For an explanation of tete-a-tete interaction, see 
TCAM's Inquiry /Response Facilities in Writing TCAM-Compatible Application 
Programs, 
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LOGICAL= ( (opfield) \ 

(^ (opfield l,switch,opfield2)j 

Function: Specifies whether a user-written routine is to be given control 
(conditionally) to test for logical errors (such as formatting errors in a card or an 
inquiry addressed to the wrong application program) in incoming messages on a 
block-by-block basis. 
Default: None. Specification optional. 

Format: (opfield) or (opfield I, switch,opfield2). opfieldl md opfield2 must 
conform to the rules for assembler language symbols, and must be the names of 
option fields defined by OPTION macros, switch may be either decimal or 
hexadecimal. If hexadecimal format is used, framing X' ' characters must be 
specified. 

Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: (opfield) specifies that a user-written routine is to be given control uncon- 
ditionally, opfield refers to a four-byte option field, the high-order byte of which 
indicates that an error has been found. The low-order three bytes are the address 
of the routine to be given control, (opfield fswitch,opfield2) specifies that the 
user-written routine specified in opfield I is to be given control conditionally if 
any of the bits on in switch are also on in the one-byte opfield! . 

If this operand is specified, STOP= or CONT= must also be specified. The user 
may initialize the routine name, option field by coding a V-type address constant 
naming his routine as part of the OPDATA= operand of the TERMINAL or 
TPROCESS macro. Upon return from the user routine, STARTMH examines the 
high-order byte of the field. If the byte is not zero and if the STOP= operand 
specifies that transmission is to be terminated, transmission is terminated. If the 
byte is zero, or if the CONT= operand is in effect, operations are restarted on the 
line. If the byte is X'04' and the STOP= operand does not specify that transmis- 
sion be terminated, TCAM will send a Reverse Interrupt (RVI) control sequence 
on a BSC line instead of the positive reply to the previous text block. (For 
additional information on RVI see the pubUcation General Information-Binary 
Synchronous Communications , GA27-3004.) This capability allows the user to 
interrupt the receipt of blocks from terminals on a BSC Hne and to send a high- 
priority message over that line. The user codes LOGIC AL= (opfield) on the 
STARTMH macro. The routine pointed to by the low-order, three bytes of the 
option field will execute an instruction that will set the high-order byte of the 
option field to X'04', if the user desires this capability. 

The user routine must save and restore registers 2 through 12, and must not alter 
the contents of register 13 and 14. On entry to the user routine the following 
registers contain: 

Register 1 — address of the four-byte option field containing the one-byte error 
indicator followed by the address of the user routine. 

Register 4 — address of the LCB (line control block), an internal TCAM control 
area described in the TCAM PLM . 

Register 6 — address of the last buffer in the block of the data (the buffer con- 
taining the EOB); this is the only buffer in this block that may be tested for 
logical errors by the user routine. 

Register 8 — address of the SCB (station control block), an internal TCAM 
control area described in the TCAM PLM . 
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Register 13 — address of a TCAM save area; must not be altered. 
Register 14 — return address for the calling routine; must not be altered. 
Register 15 — address of the entry point for the user routine. 



( int 



BREG= ( integer^ 



Function: Specifies the number of base registers desired for this MH. 

Default: BREG=1 

Format: An unframed decimal integer between 1 and 11. 

Maximum: 1 1 

Notes: One base register is required for each 4096 bytes in the MH. Assignment 

begins with register 12 and works back to 0. If BREG=3 is coded, for instance, 

registers 12, 1 1 and 10 are assigned as the base registers for the first three 4096- 

byte blocks of this Message Handler. 



L!V1D=(^YES 1 

< (opfield, switch) , 

Ino 



Function: Specifies whether this MH is to handle logical messages. 
Default: LMD=NO 

Format: YES NO or (opfield,switch), opfield must conform to the rules for 
assembler language symbols, and must be the name of a one-byte option field 
defined by an OPTION macro, switch may be either decimal or hexadecimal. If 
hexadecimal format is used, framing X' ' characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field for switch . 
Notes: YES specifies that this MH is to be used solely for handling logical mes- 
sages. If NO is specified, or if this operand is omitted, this MH is to handle each 
physical transmission as a message (without defining logical messages with the 
SETEOM macro). ( opfield,switch ) specifies that tete-a-tete interaction and 
EOB-completion handling are to be used if any of the bits on in the switch are 
also on in the option field. If the path-switch setting is to be changed for this 
message, the first buffer must not contain an EOB if a change in EOB-completion 
handhng is desired for this message. If an EOB appears in the first buffer of this 
message, the next message will be the first message affected by the change. 
LMD=YES must be coded if this MH contains a SETEOM macro instruction. If 
CONV= is coded with the ( opfield.switch ) option, LMD= cannot be coded with 
the ( opfieldySwitch ) option. Logical messages are discussed in Handling Logical 
Messages in the chapter Designing the Message Handler. 
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INBLOCK 



The INBLOCK macro 

• identifies the beginning of an inblock subgroup, 

• is required if logical messages are to be handled by this MH, or if the 
MSGFORM macro is used on input, or if a character string specified on 
MSGEDIT may cross buffer boundaries, 

• if present, must precede the inheader subgroup. 

The INBLOCK macro, when used, must be the first macro following STARTMH. 
Otherwise, the INHDR delimiter macro must be the first instruction following 
STARTMH. 

The inblock subgroup may contain one, and only one, SETEOM functional macro. 
Other functional macros that may be included in this subgroup are Usted below. 
Their positions relative to SETEOM determine whether they operate on all data in 
an entire incoming transmission sequence, or whether they operate on one or more 
blocked or deblocked logical messages; any of the following functional macros 
that are issued before the SETEOM macro act on all the incoming data in a 
physical transmission sequence, and any issued after SETEOM act on one or more 
of the resulting logical messages. 

• CODE 

• COUNTER 

• LOG 

• LOCOPT 

• MSGEDIT 

. MSGFORM 

• MSGLIMIT 

• PATH 

. SETEOM 
. TERRSET 



symbol 



Name 


Operation 


Operand 


[symbol] 


INBLOCK 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



PATH=(opfield,switch) 



Function: Specifies conditional execution of this macro. 
Default: None. Specification optional. 

Format: (opfield.switch) . opfield must conform to the rules for assembler lan- 
guage symbols, and must be the name of a one-byte option field defined by an 
OPTION macro, switch may be either decimal or hexadecimal. If hexadecimal 
format is used, framing X' ' characters must be specified. 

Maximum: 255 or a one-byte hexadecimal field for switch . 

Notes: If this operand is not specified, the subgroup is executed unconditionally. 
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INHDR 



symbol 



PATH=(opfield,switch) 



The INHDR macro 

• identifies the beginning of an inheader subgroup; 

• tests a path switch to allow alternative courses of action; 

• is required as the first macro of any incoming group if the INBLOCK macro is 
not specified. 

INHDR identifies the beginning of an inheader subgroup, in which the functional 
macros are concerned only with incoming header segments. If the inblock sub- 
group is not required, an inheader subgroup must be the first subgroup in the 
incoming group. If MSGFORM on input is specified, or if MSGEDIT is used 
across buffer boundaries, or if incoming logical messages are being handled by this 
MH, an inblock subgroup must be the first subgroup in the incoming group. Text 
segments are passed to the first inbuffer subgroup. 

INHDR determines whether an incoming message segment is a header or text 
segment (the first segment of any message is always considered to bea header 
segment). If it is a text segment or a canceled message, the segment is passed to 
the next subgroup; if it is a header segment, the inheader subgroup is executed. 

If the PATH= operand of INHDR is coded, INHDR examines a one-byte path 
switch in a field of the option table. If any of the bits specified by INHDR are on 
in the path switch, this subgroup is executed. If none of the bits are on, control is 
directed to the next subgroup. If INHDR does not specify an operand, this 
subgroup is executed unconditionally. For a more complete description of the 
path switch and its function, see Variable Processing within a Message Handler 
in this chapter. 



Name 


Operation 


Operand 


[symbol] 


INHDR 


[PATH= (opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro. 

Default: None. Specification optional. 

Format: (opfield,switch). opfield must conform to the rules for assembler 

language symbols, and must be the name of a one-byte option field defined by an 

OPTION macro, switch may be either decimal or hexadecimal. If hexadecimal 

format is used, framing X' ' characters must be specified. 

Maximum: 255 or a one-byte hexadecimal field for switch . 

Notes: If this operand is not specified, the subgroup is executed unconditionally. 
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INBUF 



symbol 



PATH=(opfield,switch) 



The INBUF macro 

• identifies a subgroup that handles incoming message buffers; 

• tests a path switch to allow alternative courses of action; 

• is optional in the incoming group. 

INBUF identifies the beginning of an inbuffer subgroup, which contains instruc- 
tions concerned with both header and text portions of incoming messages. 

If the PATH= operand of INBUF is coded, INBUF examines a path switch in a 
field of the option table. If any of the bits specified by INBUF are on in the path 
switch, this subgroup is executed. If none of the bits specified by INBUF are on 
in the path switch, processing goes to the next subgroup. If INBUF does not 
specify an operand, this subgroup is executed unconditionally. 



Name 


Operation 


Operand 


[symbol] 


INBUF 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 
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INMSG 



The INMSG macro 

• identifies the beginning of an inmessage subgroup; 

• tests a path switch to allow alternative courses of action; 

• is required as the first macro in an inmessage subgroup; 

• is optional in the incoming group. 

INMSG identifies the beginning of an inmessage subgroup. The functional 
macros associated with this subgroup are executed after an entire message or 
block has entered the system. Inmessage subgroups are specified after other 
subgroups in the incoming group. No user-written code should be included in an 
inmessage subgroup, or between such subgroups. 

If the PATH= operand of INMSG is coded, INMSG examines a path switch in a 
field of the option table. If any of the bits specified by INMSG are on in the path 
switch, this subgroup is executed. If none of the bits specified by INMSG are on, 
processing branches to the next subgroup. If INMSG does not specify an oper- 
and, this subgroup is executed unconditionally. Only one inmessage subgroup per 
message can be executed. 



INMSG causes empty buffer units at the end of a buffer processed by this Mes- 
sage Handler to be deallocated before the contents of the buffer are queued for a 
destination. Deallocated units are returned to the available unit queue. When the 
inmessage subgroup is not included in a Message Handler, this deallocation 
function is performed by the INEND macro. 



Name 


Operation 


Operand 


[symbol] 


INMSG 


[PATH=(opfield,switch)] 



symbol 



PATH = (opf ie W,switch) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



i 
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INEND 



The INEND macro 

• identifies the end of the incoming group of an MH; 

• is required as the last macro of any incoming group. 

INEND identifies the end of the instruction sequence that processes incoming 
messages. One and only one INEND macro is required for each MH with an 
incoming group, and it must be the last macro in the incoming group. No operand 
is required. 



Name 


Operation 


Operand 


[symbol] 


INEND 


(no operands) 



ymbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands for this macro. 
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OUTHDR 



The OUTHDR macro 

• identifies the beginning of an outheader subgroup; 

• tests a path switch to allow alternative courses of action; 

• is optional in an outgoing group. 

OUTHDR identifies the beginning of an outheader subgroup, which is concerned 
only with the header portions of outgoing messages and, if included, may be either 
before or after an outbuffer subgroup in the outgoing group. 

An outgoing segment is tested to see whether it is a header or a text segment. The 
outheader subgroup is executed only on a header segment; it is bypassed if the 
segment contains text only. 

If the PATH= operand of OUTHDR is coded, OUTHDR examines a path switch 
in a field of the option table. If any of the bits specified by OUTHDR are on in 
the path switch, this subgroup is executed. If none of the bits are on, control 
passes to the next subgroup. If OUTHDR does not specify an operand, this 
subgroup is executed unconditionally. 



Name 


Operation 


Operand 


[symbol] 


OUTHDR 


[PATH=(opfield,switch)] 



symboi 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



1 
% 



PATH = (opf ield,switch) 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



{ 
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OUTBUF 



ivmbol 



The OUTBUF macro 

• identifies a subgroup that handles outgoing message buffers; 

• tests a switch to allow alternative courses of action; 

• is optional in an outgoing group. 

OUTBUF identifies the beginning of an outbuffer subgroup that contains instruc- 
tions concerned with both header and text portions of outgoing messages. If 
included, an outbuffer subgroup may be located either before or after an out- 
header subgroup in the outgoing group. 

If the PATH= operand of OUTBUF is coded, OUTBUF examines a path switch 
in a field of the option table. If any of the bits specified by OUTBUF are on in 
the path switch, this subgroup is executed. If none of the bits specified by 
OUTBUF are on, control passes to the next subgroup. If OUTBUF does not 
specify an operand, this subgroup is executed unconditionally. 



Name 


Operation 


Operand 


[symbol] 


OUTBUF 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



PATH=(opfield,switch) 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 
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OUTMSG 



symbol 



PATH=(opfield,switch) 



The OUTMSG macro 

• identifies the beginning of an outmessage subgroup of an MH; 

• tests a path switch to allow alternative courses of action; 

• is required as the first macro in an outmessage subgroup; 

• is optional in an outgoing group. 

OUTMSG identifies the beginning of an outmessage subgroup, which is executed 
only after an entire block or message has been sent. Outmessage subgroups are 
specified after other subgroups in the outgoing group. 

If the PATH= operand of OUTMSG is coded, OUTMSG examines a path switch 
in a field of the option table. If any of the bits specified by OUTMSG are on in 
the path switch, this subgroup is executed. If none of the bits specified by 
OUTMSG are on, control passes to the next subgroup. If OUTMSG does not 
specify an operand, this subgroup is executed unconditionally. Only one 
OUTMSG subgroup per message can be executed. 

OUTMSG causes empty units at the end of buffers handled by this outgoing group 
to be deallocated and returned to the available unit queue. If an outmessage 
subgroup is not coded, this deallocation function is performed by OUTEND. 



Name 


Operation 


Operand 


[symbol] 


OUTMSG 


[PATH=(opfield,switch)] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies conditional execution of this macro and its subgroup. 
Notes: For details concerning this operand, see the description of the INHDR 
macro. 



( 
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OUTEND 



symbol 



The OUTEND macro 

• identifies the end of any outgoing group; 

• is required as the last macro in any outgoing group. 

OUTEND identifies the end of the instruction sequence that processes outgoing 
messages. One OUTEND macro is required for each outgoing group; it must be 
the last macro in the group. No operands are required. 



Name 


Operation 


Operand 


[symbol] 


OUTEND 


(no operands) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands for this macro. 
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Functional Macro Instructions 

This section describes the functions provided by the MH macro instructions. The 
discussion of each macro begins with a capsule summary of its functions. The 
functions of the macro are then described in detail, with a discussion of related 
topics necessary to an understanding of these functions. 

The coding of the macro is then described, using a boxed illustration. The formats 
of the macro illustrations and the symbols used are shown in Appendix A . 
General rules for interpretation of the operand descriptions are also provided in 
Appendix A , to which the reader should refer. 
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CANCELMG 



The CANCELMG macro 

• cancels messages either unconditionally or when certain errors occur (or, if 
mid-batch recovery is specified on this macro, permits the user to continue 
entering data when TCAM detects an error); 

• is optional in an inmessage subgroup (and is permitted in no other subgroup); 

• if specified, must be the first functional macro executed in the subgroup. 

For messages other than multiblock messages, CANCELMG causes immediate 
cancellation of an entire message if any errors specified by the error mask operand 
are also set in the message error record (see Appendix B for a description of the 
message error record). A canceled message is not sent to any of its destinations. 

The ERRORMSG or MSGGEN macro may be used to notify the terminal opera- 
tor of the error, or the REDIRECT macro may be used to send the message that is 
in error to a selected destination. 

For a multiblock message, CANCELMG stops processing the message from the 
point that an error is detected. Once the terminal operator resumes input (starting 
with the block immediately after the last entire block successfully entered), the 
remainder of the multiblock message is processed by this MH. 

Note: CANCELMG should not be executed for a message if an INITIATE 
macro has been executed for that message. 



If the CANCELMG macro is executed in the inmessage subgroup for a lock mode 
message, the lock is not broken and the terminal will be repoUed. 



Name 


Operation 


Operands 


[symbol] 


CANCELMG 


[mask][,CONNECT= ( AND) ] [,LEVEL=(BLK ) ] 
I OR 1 iMSGj 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



mask 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X' ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field five bytes in length. 
Notes: If the LEVEL= operand is not specified, and this operand either specifies 
an all-zero mask or is omitted, CANCELMG executes unconditionally. 



i 
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CONNECT= (AND 
/OR 



LEVEL= JBLK / 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 

OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 



Function: Specifies mid-batch recovery for errors detected in multiblock messages. 
Default: LEVEL=MSG. If mid-batch recovery is desired for incoming multi- 
block messages, this operand is required. 
Format: BLK or MSG. 

Notes: When this operand is specified and TCAM detects a permanent error after 
the first block of an incoming multiblock message, TCAM queues all error-free 
data up to the error (but not including the error) before it resumes receiving 
operations for the line. The station operator can then correctly reenter that 
portion of the message beginning with the data following the last successfully 
transmitted block. See mid-batch recovery elsewhere in this pubhcation. 

If multiple CANCELMG macros are issued in the same inmessage subgroup, only 
the first may specify LEVEL = BLK, and there may be no other macros issued 
between CANCELMG macros. 

If an error mask is specified when LEVEL=BLK is specified, the CONNECT= 
operand must specify OR. 

Example 1 : 

CANCELMG X ' 00000801 00 ' , CONNECT=AND 

specifies that the message is to be canceled only if bits 20 and 3 1 of the message 
error record are both on. 

Example 2: 

CANCELMG 524544 , CONNECT=OR 

specifies that the message is to be canceled if either bit 20 or bit 3 1 of the message 
error record is on. 
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CHECKPT 



symbol 



The CHECKPT macro 

• causes an incident checkpoint record to be taken of the option fields for the 
originating or destination station or apphcation program; 

• may be coded in any subgroup of the Message Handler except the inblock 
subgroup. 

When coded in an inheader, inbuffer, or inmessage subgroup, the CHECKPT 
macro causes an incident checkpoint record to be made of the option fields 
assigned to the originating station or application program. This checkpoint record 
is taken after the entire incoming group has executed and the message has been 
enqueued, so that the option fields reflect the fact that a message has been 
processed by the incoming group. 

When coded in an outheader, outbuffer, or outmessage subgroup, CHECKPT 
causes an incident checkpoint record to be taken of the option fields assigned to 
the destination station or application program. This checkpoint record is taken 
after the entire outgoing group has been executed and the message has been sent. 
The option fields reflect the fact that a message has been sent by the outgoing 
group. 

If a message segment goes through any subgroup in which a CHECKPT macro is 
executed, an incident checkpoint record is made after that message has been 
completely handled by the appropriate MH group. Only one record per message 
is made, even if more than one CHECKPT macro is coded in the group. If no 
CHECKPT record is coded in a group, no incident checkpoint record is made 
when the message leaves the group. 

For more information on TCAM's checkpoint facility, see the chapter Using 
TCAM Service Facilities. 

CHECKPT has the following format: 



Name 


Operation 


Operands 


[symbol] 


CHECKPT 


(no operands) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

The CHECKPT macro has no operands. 
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CODE 



The CODE macro 

• translates the data in the buffer being handled; 

• tests for operator commands; 

• is optional in the inblock, inheader, inbuffer, outheader, and outbuffer sub- 
groups (and not permitted in any other subgroups); 

• may be issued at any point in the subgroup. 

CODE causes the message segment being handled to be translated. If specified in 
an inblock, inheader, or inbuffer subgroup, translation is from line code to 
EBCDIC; if specified in an outheader or outbuffer subgroup, translation is from 
EBCDIC to the line code. Translation should not be performed in the Message 
Handler for an application program because both the Message Handler and the 
application program work on EBCDIC data. CODE may be issued with no 
translation if operator control is desired in the application program. The line code 
to be used is specified by the TRANS= operand of the DCB macro or by an 
operand of the CODE macro (which overrides the table specified in the DCB 
macro). 

If CODE is included in a subgroup, and any segments of a message are processed 
by that subgroup, the entire message is translated (special considerations for 
logical messages are discussed following the example below). Macros issued 
before CODE in the incoming group act on message characters that are in line 
code, while macros issued following CODE act on message characters that are in 
EBCDIC. The converse is true for the outgoing group. If CODE is not included 
in the incoming group, incoming messages are not translated; if CODE is not 
included in the outgoing group, outgoing messages are not translated. 

Once a message has been translated by a CODE macro executed in a subgroup of 
an incoming or outgoing group, care should be taken that no segment of it is 
routed through another subgroup when the second subgroup also contains a 
CODE macro. The second CODE macro would 'translate'' the message into 
gibberish. 

The CODE macro permits flexibility of handling of buffers with respect to 
translation by overriding the translation table specified for the line group. 

CODE tests for operator commands and transfers control accordingly. If operator 
commands may be entered by any station on a line, then a CODE macro should 
be issued in the inheader subgroup of the MH handling incoming messages on that 
line. If the LC= operand of the STARTMH macro is coded LC=OUT (that is, if 
line-control characters are to be automatically stripped from incoming messages), 
then CODE should be the first functional macro issued in either the inblock or the 
inheader subgroup for a line on which operator commands may be entered. If 
STARTMH is coded LC = IN (if line-control characters are not to be removed 
from incoming messages by TCAM), then a SETSCAN macro should be issued 
immediately before CODE. The SETSCAN macro should move the scan pointer 
to the last of the initial line-control characters. 

The user may wish to enter one or more characters in front of the character string 
that identifies his operator command. This is permissible as long as the user sets 
his scan pointer to the nonblank character immediately preceding the operator 
control character string before issuing CODE. 
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The CODE macro must be issued in either the inblock or the inheader subgroup 
handling messages from a station, if operator commands may be entered by that 
station. However, the user may not wish to translate other messages entered at the 
station. One way to avoid having to translate every message follows (assume that 
line code is removed from incoming messages). 

Code a special inheader subgroup as the first subgroup of the incoming group; this 
special subgroup may consist of a MSGTYPE macro followed by a CODE macro. 
The MSGTYPE macro examines the first field in each incoming message in Hne 
code and executes only if this field consists of some specific character — for 
instance A. Enter A before the identification sequence of each operator com- 
mand. If the first character of a message is A, the CODE macro will execute, and 
the message will be translated — otherwise, control will be passed to the next 
delimiter, which may be another inheader subgroup designed to handle messages 
other than operator commands in line code. 

Example: 

The following code might be used to check for operator commands entered at a 
1050 station, and to cause each incoming message to be translated only if it is ail 
operator command. It is assumed that line code is removed from incoming 
messages and that the operator at the station enters an A immediately in front of 
the identification sequence for an operator command. 

OCMH STARTMH LC=OUT , STOP=YES 

OCCFIK INHDR 

MSGTYPE X'E2' 

CODE 
NONOC INHDR '4 

INBUF 

INMSG 

INEND 

An incoming message enters the first inheader subgroup. If A (which is X'E2' in 
1050 line code) is the first character in the message, CODE is executed. If this is 
an operator command, the CODE macro causes it to be handled as such, and it 
never reaches the second inheader subgroup. A message that does not begin with 
A is not translated and is passed to the second inheader subgroup, which contains 
macros that handle ordinary (not operator control) messages. 

The CODE macro instruction provides the same functions for logical messages 
(translation and checking for operator commands) as those described above. 
However, the following special considerations apply to the CODE macro when it 
is used in the inblock subgroup handling incoming messages to be deblocked into 
multiple logical messages. Logical messages formed by blocking incoming physi- 
cal transmissions require no special considerations. Logical messages are dis- 
cussed in Handling Logical Messages in this chapter. 
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The format of an incoming physical transmission that is to be deblocked is 




E 
O 
M 



^ 



m^. 



E 
O 

M 



^^^^Mfei^^ 



M 



M^^^/I^^^&l 



E 
O 

T 



symbol 



( tablename 

^NONE 
I (register) 



where P is all the data in the entire physical transmission and L1-L3 are the logical 
messages that will result from deblocking P. 

When the CODE macro is issued in the inblock subgroup before the SETEOM 
functional macro, all the incoming data (P) is translated. If logical messages LI, 
L2, and L3 are to be checked to determine if they are operator commands, the 
inheader subgroup of this incoming group must contain another CODE macro 
specifying NONE. 

When issued after the SETEOM macro, CODE functions in the same manner as 
described in the section preceding the example above, except that the CODE 
macro cannot be used to check for operator commands. 

CODE has the following format: 



Name 


Operation 


Operands 


[symbol] 


CODE 


[^tablename^ ] 

<[none . > 

((register) ) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary .) 



Function: Specifies the type of translation to be done. 

Default: None. Specification optional. 

Format: tablename, (register) or NONE, tablename must either be one of the 

names permitted for the TRANS = operand of the DCB macro or the name of a 

user-defined table that conforms to the rules for assembler language symbols. 

(register) must specify a decimal integer between 2 and 1 1 . 

Notes: If this operand is omitted, the table used for translation is that specified by 

the TRANS= operand of the DCB macro. 

If NONE is specified, the message is not translated. None can be used to check 
for operator commands when the station transmits in EBCDIC. 
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If (register) is specified, the register must previously have been loaded with the 
address of the table to be used* A user-defined translation table must consist of a 
fuUword on a fuUword boundary, followed by a 256-byte table for translating (| 

from Une code into EBCDIC^ followed by a 256-byte table for translating from 
EBCDIC into hne code. The first word must contain the address of the first byte 
of the second table. The high-order byte of the first word must be zero. 
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symbol 



LIST=name 



lVIAXDEEP=mteger 



COMMBUF 



The COMMBUF macro 

• is optional in the inheader and inbuffer subgroups of an MCP that supports 
3670 terminals equipped to receive broadcast messages; 

• routes broadcast messages to the destinations specified in the indicated TLIST 
macro. 

COMMBUF has the following format: 



Name 


Operation 


Operand 


[symbol] 


COMMBUF 


LIST=name,MAXDEEP=integer 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of a TLIST macro that should contain the names of 
the broadcast terminals (TERM=367C on the TERMINAL macro). 
Format: Must conform to the rules for assembler language symbols. 



Function: Specifies the maximum number of broadcast operations that may be 

scheduled for a line at any one time. 

Default: None. This operand must be specified. 

Format: Unframed decimal integer greater than zero. 

Maximum: 65535 

Notes: The COMMBUF macro moves the data in the current buffer into one of 

the data areas specified at INTRO time. Therefore, any MH macros following 

COMMBUF will have no effect on the data sent by the common buffer facility. If 

the length of the data to be moved is greater than the size of a data area, the 

macro will not execute, and a return code will be given in register 15 (see return 

codes). 
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The common buffer facility allows data entering the input MH to be sent without 
being queued. There is no outgoing message handhng capability for this data. 
The data in the current buffer will be moved to the next available data area, and a 
broadcast operation will be scheduled for each of the lines whose broadcast 
terminals are named in the TLIST macro if the MAXDEEP= value has not been 
exceeded and if the line is active. If the MAXDEEP= value has been exceeded, 
the data in the current buffer is not moved and is not broadcast. 

Framing line control characters (STX, ETX) must be supplied by the user and 
there should not be any embedded ETBs. 

COMMBUF will return the following codes in register 15: 

00 Good return 

04 Data area too small; macro did not execute (the data area size specified 

in the COMMBUF = operand of the INTRO macro was too small). 

08 MAXDEEP value exceeded (register 1 will contain the number of 

times MAXDEEP was exceeded). 

OC LIST= operand specified a name that was not a TLIST entry. 



< 
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I 



COUNTER 



The COUNTER macro 

• maintains a count of complete messages or of message segments received from 
or sent to a station; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups. 

COUNTER enables the user to maintain four types of count. The position of the 
COUNTER macro within an MH determines which type of count is maintained. 
COUNTER may appear: 

• in the inblock subgroup to count incoming physical message segments arriving 
at this MH, or incoming logical message segments for each originating station; 

• in the inheader subgroup to count incoming messages for each originating 
station; 

• in the inbuffer subgroup to count incoming message segments for each originat- 
ing station; 

• in the outheader subgroup to count outgoing messages for each destination 
station; 

• in the outbuffer subgroup to count outgoing message segments for each destina- 
tion station. 

Any one or more of the counts may be maintained by including COUNTER in the 
appropriate subgroups; within each subgroup, it may appear at any point. 

For each COUNTER macro, the user must define, by an OPTION macro, a 
halfword option field for the appropriate station or component. This provides 
space for maintaining the counters. 

The use of COUNTER is optional. If it is used in either an inheader or or an 
inbuffer subgroup for switched stations that do not have unique ID sequences, and 
if a calling station that enters a message is not identified by an ORIGIN macro 
before COUNTER is executed, the option field associated with the related Une 
entry in the terminal table will be referred to. 

Note: The count may not be exact since recalled messages (from 
ERRORMSG, for instance) and messages from buffered stations will be 
counted twice. 

If the MH includes the SETEOM macro, the number of times the COUNTER 
macro executes depends on the PROCESS = operand of SETEOM and on the 
position of the COUNTER macro relative to the SETEOM macro. 

If the SETEOM macro specifies PROCESS=NO, the COUNTER macro always 
adds one to the counter for each resulting blocked logical message. 

If the SETEOM macro specifies PROCESS=YES, and if the COUNTER macro 
appears before SETEOM, one is added to the counter to reflect each buffer in the 
entire incoming transmission sequence; however, if COUNTER appears after 
SETEOM (that is, after the data is deblocked), each buffer of each resulting 
logical message causes a counter to be updated by one. In the latter situation, if a 
counter is associated with each station that is eligible to enter messages to this 
MH, a count is maintained for incoming logical messages on a station basis. 

Logical messages are discussed in Handling Logical Messages in this chapter. 
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symbol 



opfield 



Name 


Operation 


Operands 


[symbol] 


COUNTER 


opfield 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the half word option field in which the count is to 

be maintained for the station or component. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols and must be 

the name of a halfword option field defined by an OPTION macro. 

Notes: The field contains a binary count up to a maximum of 65535. When the 

maximum count has been reached, the count is reset to zero for the next message 

or segment counted. 

The user may gain access to the field at any time to determine or reset the count 
(by operator commands or by user code including the LOCOPT macro). The 
count is initially set using the OPDATA= operand of the TERMINAL or 
TPROCESS macro. 



If the option field is not found. COUNTER does not execute and control passes to 
the next MH instruction. A return code of XTF' in the low-order byte of register 
15 indicates that COUNTER did not execute. 



( 
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CUTOFF 



symbol 



integer 



The CUTOFF macro 

• specifies the maximum allowable length of incoming messages; 

• checks for incoming buffers filled with identical characters; 

• is optional in the inbuffer subgroup (and not permitted in any other subgroup); 

• is usually issued before a related ERRORMSG macro. 

CUTOFF specifies the maximum number of characters allowed in an incoming 
message. If the maximum number is reached, reception of data is terminated as 
soon as those buffers already assigned to the Une have been filled, an error flag is 
set in bit 7 of the message error record for the message (see Appendix B ). 
CUTOFF also turns on bit 7 of the message error record if the input buffer is 
filled with identical characters (usually an indication of station malfunction). 

An ERRORMSG macro may be used in the same incoming message handler as the 
CUTOFF macro to test bit 7 of the message error record and to notify the 
terminal operator that reception of the message has been terminated. The opera- 
tor can determine if the allowed number of characters was exceeded; otherwise a 
station malfunction is indicated. After the CUTOFF macro has executed, 
processing continues through the inbuffer subgroup. 



Name 


Operation 


Operands 


[symbol} 


CUTOFF 


integer 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Function: Specifies the maximum number of characters allowed for each message. 

Default: None. This operand must be specified. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' or 

XLn* ' characters must be specified. 

Maximum: 65535 or a hexadecimal field of two bytes. 

Example: 

CUTOFF 400 

specifies that reception of the message is to be terminated after 400 characters 
have been entered. 

CUTOFF does not provide a precise limit to the number of characters in an 
incoming message (because TCAM continues to read until the buffers currently 
assigned have been filled). The inmessage subgroup is not executed until the line 
operation has terminated. When the CUTOFF condition is encountered, a Write 
Break is issued for the Telegraph Adapter I. For IBM Adapter III Model 1, a 
2848 Read Skip with 2848 Break is issued. For all other devices, a Read Skip is 
issued when the CUTOFF condition is encountered. 

Note: Once the CUTOFF condition is encountered, the CUTOFF macro 
must be executed for each subsequent buffer of the message. 
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symbol 



DATETIME 



The DATETIME macro 

• inserts the date, the time, or both in an incoming or outgoing message header; 

• is optional in inheader and outheader subgroups (and not permitted in any 
other subgroup); 

The DATETIME macro causes insertion of the date, the time, or both the date 
and the time into the header of an incoming or outgoing message. (If both are 
specified, the date is inserted first.) Seven characters are inserted for the date, if 
specified: a blank, the last two digits of the year, a period, and the three-digit day 
number. Nine characters are inserted for the time, if specified: a blank, two digits 
for the hour, a period, two digits for the minute, a period, and two digits for the 
second. If no operand is coded, both the date and the time are provided (the 
operands specify which is to be omitted). 

Space in the header for these insertions, seven characters for the date and nine 
characters for the time, must be reserved by the RESERVE= operand of the DCB 
macro for the communication line or by the RESERVE = operand of the PCB 
macro for the application program, if the insertions are desired. After 
DATETIME has executed, the scan pointer is positioned at the last inserted 
character. 

When the DATETIME macro is coded in an outgoing subgroup, the macro may 
operate upon the first message segment only. This is because TCAM does not 
maintain reserve bytes for any segment of an outgoing message except the first 
(see the description of the RESERVE= operand of the DCB macro). 

To avoid having to specify a large first buffer, the user who wishes to insert both 
the date- and time-received and the date- and time-sent in the same message 
header may design his header so that it occupies two buffers. He could then insert 
the incoming date and time in that portion of the header contained in the second 
buffer, and the outgoing date and time in that portion of the header contained in 
the first buffer. 

The characters inserted by DATETIME are in EBCDIC code. Therefore, the 
DATETIME macro should not be issued before a CODE macro in an inheader 
subgroup, or after a CODE macro in an outheader subgroup. 



Name 


Operation 


Operands 


[symbol] 


DATETIME 


[DATE= J NO V|[,TIME=f NO ^ 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary .) 



) 
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DATE=(NO ) 
)YES\ 



Wes{ 



Function: Specifies whether the date is to be inserted in a message header. 

Default: DATE=YES 

Format: YES or NO. 

Notes: YES specifies that the date is to be inserted in the message header. NO 

specifies that the date is to be omitted from the header. 



Function: Specifies whether the time is to be inserted in a message header. 

Default: TIME=YES 

Format: YES or NO. 

Notes: YES specifies that the time is to be inserted in the message header. NO 

specifies that the time is to be omitted from the header. 

If no operand is coded, both the date and the time are inserted in the message 
header. 

The time inserted is the time at which this DATETIME macro is executed. 
TCAM determines this by examining the system timer. 

If insufficient buffer space is available (too few reserve characters), the 
DATETIME macro does not execute and a X'04' return code is set in register 15. 

Example: 

The message 

NYC 0039 * ( message text ) EOT '4 

is entered at the NYC terminal (NYC is the origin, 0039 the input sequence 
number). If the header buffer is being processed at 9:45:50 p.m. on February 6, 
1970 and if the SEQUENCE macro is followed by DATETIME DATE=NO, the 
time is inserted in the header, which becomes: 

NYC 0039 2 1 . 45 . 50 * ( message text ) EOT 

If the SEQUENCE macro is followed by DATETIME, the header becomes: 

NYC 0039 70.037 21 .45.50 * (message text ) EOT 
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ERRORMSG 



The ERRORMSG macro 



• sends an error message when an error occurs; 

• is optional in an inmessage or outmessage subgroup of an MH (and not permit- 
ted in any other subgroup); 

• may be used more than once in a subgroup. 

ERRORMSG sends an error message specified by the user to a designated station 
when errors indicated by the error mask have occurred. The bits specified by the 
error mask operand are compared with the setting of the bits in the message error 
record for this message; if specified bits in the message error record are on, the 
error message is sent. The message may be sent unconditionally by specifying an 
all-zero mask, or by omitting the mask. 

The message sent to the station includes the text written by the user preceded by 
the header of the message in error, which is recalled from the message queue. The 
error message, once formatted, is placed on the destination queue for the station 
selected to receive the message, and is handled by the outgoing group of the MH 
for that queue. Therefore, unless a MSGTYPE or PATH macro is used to distin- 
guish between different message types, the format of the header of the message in 
error must be compatible with the macros executed in the outgoing group handling 
messages routed to the station selected to receive the error message. If the 
MSGTYPE macro is used for this purpose, the formats of the respective headers 
may differ after the message-type character. 

y The outgoing group that handles the error message for the destination station may 

^ have an outmessage subgroup containing ERRORMSG and REDIRECT macros. 

TCAM causes these macros to NOP; that is, TCAM does not generate subsequent 
error messages based on an error condition related to the original error message 
(thus preventing a "snowball" effect of error messages); and TCAM does not 
permit the error message to be redirected to an alternate destination. 

If the MSGFORM macro is not coded in the outheader subgroup of the MH 
handling messages for the destination station, the user must ensure that satisfacto- 
ry line-control characters (such as EOT) are included in his error message. 

The user may prefer to use the MSGGEN function if the message header is not 
required as a part of the error message. The user is notified of the error sooner if 
he uses MSGGEN than ERRORMSG, but ERRORMSG returns the header of the 
message in error, while MSGGEN does not. If it is necessary to send an error 
message for input errors when no data has been transferred, the MSGGEN macro 
must be used because the ERRORMSG macro requires a header. 

If cancellation of an erroneous message is required, the CANCELMG macro must 
have been issued before the ERRORMSG macro. ERRORMSG may appear in 
inmessage and outmessage subgroups and can appear more than once in either 
subgroup. 

Since the header of the message in error is recalled from the destination queue, it 
is not possible to use ERRORMSG coded DEST=DESTIN when the destination 
of the message in error is not known to TCAM. If a message having an invaUd 
1 destination field is entered, and the destination is not corrected by the user-exit of 

^ the FORWARD macro, and if no dead-letter queue is specified by the INTRO 
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symbol 



macro, then ERRORMSG cannot be used in conjunction with that message, 
because the message header is not on a destination queue (consequently, TCAM 
cannot get a copy of the header by recalling it from a destination queue). 



Name 


Operation 


Operands 


[symbol] 


ERRORMSG 


[mask][,CONNECT= lANDM 
<OR > 

[,DEST= /'destination name^] 
)opfield ( 
) ORIGIN r 

(destin ) 

,D ATA = J message ) 
I fieldname) 
[, EXIT = name of routine] 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



mask 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in AppendijS ) 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X * ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 
Notes: Omitting this operand or specifying an all-zero mask causes uncondition- 
al execution. 






CONNECT=JAND/ 
JOR S 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 

OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 



DEST= ( destination name "; 
) opfield 
) ORIGIN 
V DESTIN 



Function: Specifies the destination for the error message. 

Default: In an inmessage subgroup, DEST= ORIGIN. 

In an outmessage subgroup, DEST=DESTIN. 

Format: destination name, opfield, ORIGIN or DESTIN. destination name is the 
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DATA= { message ) 
( fieldname ) 



name of a single or a process entry in the terminal table and must be enclosed in 
framing C ' or CLn* ' characters. 

opfield is the name of an option field defined by an OPTION macro, conforming 
to the rules for assembler language symbols, which contains the name of a single 
or process entry in the terminal table. It must not be specified with framing 
characters, opfield is a field from two to nine bytes, with the first byte containing 
the decimal length of the rest of the field. 

ORIGIN specifies that the error message is to be sent to the station from which 
the message originated. This operand may be specified in either an inmessage or 
outmessage subgroup. If the originating station is not known (because it called in 
on a switched line and did not identify itself) the message is sent to the dead-letter 
queue if one is specified, otherwise it is lost. 

DESTIN specifies that the error message is to be sent to the destination station 
specified in the header of the message in error. This operand may be specified in 
either an inmessage or outmessage subgroup. 

Notes: If an invaUd destination is specified, or if DESTIN is specified in an 
inmessage subgroup for which no FORWARD macro has been issued previously, 
the message is sent to the dead-letter queue if one has been specified by the 
DLQ= operand of the INTRO macro. If no dead-letter queue is specified, the 
message is overlaid and lost. 

A distribution Ust or a PUT process entry must not be specified as the destination 
of an error message. 



Function: Specifies the error message. 
Default: None. This operand must be specified. 

Format: message or fieldname, message is the actual error message to be sent 
and must be specified within framing C ' or CLn' ' characters, fieldname is the 
name of a location containing in its first byte a binary count of the number of 
characters in the message, followed by the message itself. The error message is a 
maximum length of 255 characters. This is exclusive of the binary count in the 
fieldname format. 

Notes: If an error message is longer than a single buffer unit, one additional 
buffer unit is obtained and as much of the remainder of the message as will fit is 
placed in it. If the entire message will not fit into these two units, the remainder is 
truncated on the right. 



EXIT = name of routine 



Function: Specifies the name of a user- written routine that alters error message 
processing. This exit may be used to alter the text of the error message before 
incorporating the text into a header buffer. 
Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 
Notes: If the user provides an exit routine for ERRORMSG, TCAM automati- 
cally saves and restores registers for this routine. The user need not save registers 
and may change the contents of registers 2 through 12; however, the contents of 
register 13 and 14 should not be altered by the user routine. When the routine 
receives control, register 1 contains the address of the header buffer and register 5 



Designing the Message Handler 227 



contains the address of the error-message text. Register 14 contains the return 
address for the caUing routine. Register 15 contains the address of the entry point 
for the user routine. TCAM expects no return code from the user routine. The 
routine should return control to TCAM by a BR 14 instruction. 

When ERRORMSG is executed, only the first buffer of the message in error is 
retrieved from the destination queue (if the header occupies more than one buffer, 
that portion of the header extending beyond the first buffer is not retrieved). The 
actual error message is placed in that portion of the first header buffer that 
contains message text; the error message overlays the text. If the first buffer is 
entirely filled with header information, or does not contain enough space after the 
header to hold the entire error message, TCAM automatically assigns one extra 
unit to the buffer to hold as much as possible of the remainder of the message. If 
the entire message will not fit, the remainder is truncated on the right. 

The message is inserted in the header beginning at the current location of the scan 
pointer. If an ERRORMSG macro is issued in the inmessage subgroup, but there 
is additional header information that could be recognized by the outheader 
subgroup, the message will overlay this data, which will be lost for outgoing 
processing. If data has been inserted or removed during inbuffer or outbuffer 
processing, the data in the buffer will be moved either to the right or the left while 
the scan pointer remains fixed. Thus, when the error message is inserted at the 
scan pointer, data that is logically part of the header may be lost, or data beyond 
the header may be included as part of the header information returned with the 
message. 



i 



228 OS/MFT and OS/MVT TCAM Programmer's Guide 



FORWARD 



The FORWARD macro 

• queues messages for one or more specified destinations; 

• sets a bit in the message error record when a specified number of queued 
messages is exceeded for a destination using main-storage-only queuing; 

• is required in each inheader subgroup of the MH for every station and applica- 
tion program that can enter messages directed to a specific destination. 

FORWARD allows scanning of the destination code field in the header of each 
incoming message and compares the field with the names of the terminal table 
entries. If the destination code is valid (a matching entry is found in the terminal 
table), FORWARD queues the message for the specified destination or destina- 
tions. If an invalid destination code (that is, one not appearing in the terminal 
table) is detected, control passes to the user routine specified by the EXIT= 
operand of FORWARD. If no user exit is specified, the message is queued for the 
station or application program specified by the DLQ= operand of the INTRO 
macro. If no station or application program is specified by DLQ=, and no user 
exit is provided, messages with invalid destination codes are overlaid and lost. 

Messages may be routed to one or more destinations: 

1 . To the single destination specified in the message header or named by an 
operand of the FORWARD macro. 

2. To the distribution Ust specified in the message header or named by an operand 
of the FORWARD macro. 

3. To the cascade list specified in the message header or named by an operand of 
the FORWARD macro. 

4. To the multiple destinations specified in the message header. The destination 
codes may be of equal length or of varying lengths. In the case of multiple 
destinations, an operand specifies the end-of-address character or characters 
included after the last destination code in the header of each incoming message. 

5. To the group entry in the terminal table specified in the message header or in 
an operand of the FORWARD macro. 

When multiple destinations are specified, only the first is checked for vaUdity at 
execution of the FORWARD macro. The secondary destinations are checked for 
validity only after the entire message has been received. The first invalid destina- 
tion will be routed to the station specified by the DLQ= operand of the INTRO 
macro otherwise it will be lost; any other invalid destinations will be ignored. 

If multiple destinations are specified in the message header, or if a distribution Ust 
is specified, once the incoming group has finished processing the message, copies 
are made and routed to the destination queue for each destination specified in the 
header or distribution list. 

A FORWARD macro must be included in each inheader subgroup handling 
messages destined for stations or application programs; otherwise the incoming 
group of the MH does not know where to route the message. 

If DEST= (number) or DEST=** is specified, the CODE macro must be executed 
before FORWARD, unless the line code is EBCDIC. 
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If DEST=ORIGIN is specified, the ORIGIN macro must be executed before the 
FORWARD macro for messages from switched terminals that do not have a hne 
entry. 

Note: Care must be taken in entering a character string in a destination 
field to ensure that it matches a terminal table entry, A character string 
entered in lower-case characters from an IBM 2770 station, for example, 
will not match a terminal table entry name that is in uppercase characters. 

FORWARD has the following format: 



Name 


Operation 


Operands 


[symbol] 


FORWARD 


[DEST=|destname 1 ] 
\opfield / 
)( number) ( 

JpUT ( 
1 ORIGIN \ 
\ REG(number) J 

[ ,EO A = characters] 

[,EXIT=name] 

[,THRESH=nn] 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 






DEST= I destname 
opfield 
(number) 

PUT 

** I 

ORIGIN 
REG(number) 



Function: Specifies the destination for the message. 
Default: DEST=** 

Format: destname, opfield, (number), PUT**, ORIGIN, or REG(number). 
destname is the name of a single, group, distribution list, cascade list, or process 
entry in the terminal table and must be specified with framing C ' , CLn' ', X' \ or 
XLn* ' characters, opfield is the name of a field defined by an OPTION macro 
containing the name of an entry in the terminal table. Framing characters must 
not be used, (number) is the number of characters in each of a list of one or more 
destinations. PUT is specified when the destinations of messages entered by an 
appUcation program are placed by the user in an application program work area. 
** specifies that there are one or more destination names of variable length in the 
message header. ORIGIN indicates that the message is to be returned to the 
originating station. REG(number) specifies the register containing the address of 
a work area that contains the name of the destination. 
Maximum: number can be a decimal field with a maximum value of 8. 
Notes: opfield refers to an option field that is 1 to 8 bytes. If the destination 
name is shorter than the length of the option field, the name must be padded to 
the right with blanks to fill the field. 
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EOA= characters 



EXIT=naine 



If (number) is specified, the destination names in the message header must all be 
the same length. Delimiting and embedded blanks are ignored. If this operand is 
specified and there is more than one destination, the EOA= operand must also be 
specified. 

If ** is specified, delimiting blanks must be used between destination names in the 
header, but there may not be any embedded blanks. If this operand is specified 
and there is more than one destination in the message, the EOA= operand must 
also be specified. 

DEST=PUT should be specified in the inheader subgroups of the MH assigned to 
an application program when the MH is to handle messages coming from an 
application program that has OPTCD=W coded in its output DCB macro, if the 
user wishes the message to go to the destination specified in the work area. For 
more information on specifying the destination of a message in the application 
program, see the discussion of the OPTCD= operand of the output DCB macro. 
Use of this operand is restricted to the case just described. 

If an invalid destination is specified, control passes to the user routine specified by 
the EXIT= operand. If no user exit is specified, the message is queued for the 
station specified by the DLQ= operand of the INTRO macro. If no station is 
specified by DLQ= and no user exit is provided, messages with invahd destination 
codes are overlaid and lost. 

If REG (number) is specified, register 2 through 12 may be used. The register must 
contain the addtess of a field that has the following format: 

byte = length of the destination name. 

byte 1 - n = destination name with the same characteristics and format as 

destname when BEST = destname. 



Function: Specifies the character or character string used after the last station 
name of a mutiple destination to delimit the destination field of the header. 
Default: None. With DEST= coded destname , opfield , or PUT, specification 
optional. With DEST= coded (number) or ** and multiple destinations in the 
message, this operand is required. 

Format: One to eight nonblank characters specified in character or hexadecimal 
format. If character format is specified, the field may be unframed or framed with 
C* ' or CLn' ' characters. If hexadecimal format is specified, the field must be 
framed with X' ' or XLn' ' characters, n must be the actual length of the charac- 
ters. 

Notes: If this operand is specified and DEST= is coded destname , opfield or 
PUT, the operand is ignored. 



Function: Specifies the name of a user-written exit routine that is given control 

when an invahd destination is detected. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The routine may correct the destination, provide another destination, or 

indicate that the message is not to be processed for a destination. If an invalid 

destination is provided by the user exit routine, the message is forwarded to the 

dead-letter queue if one is specified by the DLQ= operand of the INTRO macro. 

Otherwise it is overlaid and lost. 
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THRESH=nii 



If the user provides an exit routine for FORWARD, TCAM automatically saves 
and restores registers for this routine. The user routine need not save registers 
and may change the contents of registers 2 through 12. However, the contents of 
register 13 and 14 should not be altered. When the user routine receives control, 
register 1 contains the address of the header buffer. Register 14 contains the 
return address for the calling routine. Register 15 contains the address of the 
entry point for the user routine. 

TCAM expects the user routine to place one of two items in register 15 before 
returning control: 

• A return code of all zeros in register 1 5 means that the user routine was unable 
toprovide a satisfactory destination for this message. In this case, the message 
is forwarded to the dead-letter queue or is not processed for any destination if 
no dead-letter queue is provided. 

• Register 15 may contain the main-storage address of a field set up by the user 
and consisting of a length byte followed by the name of a valid single, group, 
distribution Ust, cascade list, or process entry in the terminal table. The length 
byte must contain in binary form the number of bytes in the rest of the field. 
TCAM assumes that the specified name is the destination of the message. The 
field must be padded to the right with blanks to the length of the longest entry. 

The user routine should return control to TCAM by a BR 14 instruction. 
This operand is ignored when DEST=PUT is specified. 



Function: Sets a bit in the message error record indicating that a user-specified 
number of messages have been queued for a destination that uses main-storage- 
only queuing. 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X* ' or 
XL2* ' characters must be specified. 
Maximum: 65535 

Notes: nn is a user-specified number that indicates the maximum number of 
messages expected to be queued at any one time under normal traffic conditions 
for a destination that uses main-storage -only queuing. This operand causes 
TCAM to queue a message and set bit six in the message error record when the 
number of messages queued exceeds nn . 

If the destination is an application program, this operand permits the user to delay 
activation of an apphcation program until a certain number of messages are 
queued for that destination. This operand can be used also as an aid in controlling 
the efficient use of system resources when one or more destinations use main- 
storage-only queuing. For instance, to prevent main storage being tied up with 
unsent messages, the user might provide a warning of an excessive number of 
messages queued for a particular destination; he could then issue a conditional 
macro in his inmessage subgroup such as CANCELMG, REDIRECT, 
ERRORMSG, and MSGGEN. If there are multiple destinations, the REDIRECT, 
ERRORMSG, and MSGGEN macros are effective only if the number specified by 
nn is exceeded for the first destination. 

In order for this function to be provided for a destination, the destination station's 
entry in the terminal table must not specify either a cascade Hst entry or a distri- 
bution Ust entry (that is, do not code a TLIST macro in the terminal table for this 
destination station). 
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In the case of multiple-buffer headers, a destination must be determined for the 
first header buffer. This can be ensured in one of two ways as the first header and 
the subgroup are designed: 

1. If the destination is specified by the DEST= operand, the FORWARD macro 
must occur sufficiently early in the subgroup that it acts upon the first header 
buffer. 

2. If the destinations are specified in the header rather than by the DEST= 
operand, the first destination must be completely contained within the first 
buffer. For buffered terminals, the first destination must appear in the first 
hardware buffer or the first MCP buffer, whichever is smaller. 

If the second condition is not met, TCAM assumes that an invalid destination has 
been specified and branches to the user exit, if provided. If no user exit is provid- 
ed, or if the first condition is not met, the message is routed to the dead-letter 
queue, or is overlaid and lost, if no dead-letter queue is provided. 
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HOLD 



The HOLD macro 

• suspends transmission to a station; 

• is optional in the inheader, inmessage, and outmessage subgroups. 

HOLD suspends transmission of output messages to a station either for a time 
interval or until t|ie messages are released by a RESMXMIT operator command or 
by an MRELEASE macro issued in an application program (except that resump- 
tion is automatic if this MH is handling logical messages). HOLD may be request- 
ed unconditionally by specifying an error mask of zero or by omitting the mask, 
or conditionally, in which case the error mask specified in the first operand is 
compared to the message error record assigned to the message; if specified errors 
are detected, transmission is suspended. A station that cannot accept messages 
because of the effect of a HOLD macro is said to be intercepted . For a discussion 
of holding, see the section TCAM's Hold/ Release Facility. 

When issued in the outmessage subgroup of an MH handling logical messages, the 
HOLD macro permits the user to transmit a buffer containing an error as soon as 
it is detected. If a transmission interval is specified by HOLD, resumption of 
transmission begins with the block in error (the error block is transmitted 
twice — once when the error is detected, and once when transmission resumes). If 
an interval is not specified, transmission resumes immediately, and the error block 
is transmitted twice. 

An inquiry/response facility is provided by the HOLD/MRELEASE macro 
combination (see TCAM's Inquiry /Response Capabilities in the section Writing 
TC AM -Compatible Application Programs ). The HOLD macro, when issued in 
the inheader subgroup of a Message Handler, suspends transmission of outgoing 
messages to the station entering the message until an MRELEASE macro in an 
application program releases the station. 

By using the macros in combination with TCAM's message priority capability, it is 
possible to ensure that after the intercepted station enters an inquiry the next 
message received by it will be the response from an appUcation program to that 
inquiry. 

If specified in an inheader subgroup, HOLD will supply a return code in register 
15 that can be checked by the next instruction in the MCP. The return codes are: 

X'OO' Sucessful execution. 

X*04' Destination queue is located in main storage with no disk 

backup. 

X*08' Station is already held. 

X'OC Station cannot be held because it is a process entry, cascade 

or distribution list, etc. 

X* 10' Invalid terminal entry address returned by terminal entry 

address finder routine. 

A station whose destination queue is located in main storage with no disk backup 
may not be intercepted; the HOLD macro is ignored in this case. 
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In the inheader subgroup, suspension of transmission begins with the message that 
causes the HOLD macro to execute. Otherwise, suspension begins with the 
message following the one that causes the HOLD macro to execute (since the 
outmessage subgroup does not execute until after the message has been sent). 
However, when the station is released, the message that caused HOLD to execute 
is retranmitted, unless HOLD was executed in the inheader subgroup and the 
message was routed to another station. 

If an initiate mode message is sent to a held terminal, the message will revert to 
standard transmission (rather than initiate transmission). However, it will be 
queued on the highest-priority queue and be transmitted normally thereafter. 

If the HOLD macro is executed in the outmessage subgroup for a lock response, 
the lock is not broken, the terminal is not held, and the message will be retransmit- 
ted immediately (that is, it will be sent twice). This can result in an infinite loop if 
the condition for the HOLD is permanent and the line or terminal is inoperative. 
If a terminal is held by an operator command while in lock mode, or if lock is 
initiated while the terminal is held, all lock responses will be sent as if the terminal 
were not held. No other messages will be sent, however, until the terminal is 
released. 



Name 


Operation 


Operands 


[symbol] 


HOLD 


[mask][,RELEASE][,INTVL=mteger] 
[,CONNECT= JANDh [,LEVEL= JBLK / ] 
)OR ( )MSG( 



symbol 



mask 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X* ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 
Notes: Omitting the operand or specifying an all-zero mask causes unconditional 
execution (unless LEVEL=BLK is specified, which causes conditional execution; 
LEVEL =BLK causes a mask to be generated and the text and selection bits to be 
set in the message error record). 

If queuing is by line and a nonzero mask is specified, the mask must include the 
test for the "terminal inoperative" bit of the message error record. 



RELEASE 



Function: Specifies that transmission to the station is to be suspended until either 
a RESMXMIT operator command is issued for the station, or until an 
MRELEASE macro is issued for the station in an application program. 
Default: See Notes 
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INTVL=integer 



Format: RELEASE 

Notes: Do not code this operand if this MH handles logical messages (TCAM 
automatically resumes transmission). If logical messages are not being handled by 
this MH, and if this operand is omitted and INTVL= is also omitted, RELEASE is 
assumed; if both RELEASE and INTVL= are coded, RELEASE prevails. 
RELEASE should not be specified if LEVEL =BLK is specified. 



Function: Specifies the number of seconds that transmission to the station is to be 
suspended. 

Default: None. Specification optional. 

Format: Positive integer, either decimal or hexadecimal. If hexadecimal format is 
used, framing X* ' or XLn' ' characters must be specified. 
Maximum: 65535 or a hexadecimal field of two bytes. 

Notes: At the end of the specified period, transmission to the station is automati- 
cally resumed. If this operand i^ omitted and this MH handles physical transmis- 
sions, RELEASE is assumed. If both RELEASE and INTVL= are coded, 
RELEASE prevails. If this MH handles logical messages, TCAM automatically 
resumes transmission after the specified time interval; if this operand is omitted, 
resumption is automatic. 

The INTVL= operand may not be coded if the HOLD macro is to be executed in 
the inheader subgroup. It is ignored for nonswitched and buffered stations during 
mid-batch recovery operations. 



CONNECT=JAND/ 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 



i 



OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 

The TCAM checkpoint/restart facility permits restart of a TCAM system after 
system closedown or failure. If the system fails or is closed down while the station 
is intercepted, when the system is restarted by a warm start or a continuation 
restart (defined in the discussion of the checkpoint/restart facility) the intercep- 
tion will still be in effect, but the INTVL= operand will no longer apply; transmis- 
sion will be suspended until a RESMXMIT operator command or MRELEASE 
macro causes transmission to be resumed. 



LEVEL= J BLK ( 
<1VISG1 



Function: Causes a message containing an error to be retransmitted. 

Default: LEVEL=MSG 

Format: BLKorMSG. 

Notes: This operand is required in any subgroup for which mid-batch recovery is 

desired (see Mid-Batch Recovery in the chapter Using TCAM Service 

Facilities ). Use of this operand requires that MB=YES be specified on the source 

station's TERMINAL macro if the source is a nonswitched station (need not be 
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specified for switched or buffered stations). In an inmessage subgroup, if the 
MB= operand is omitted or if it specifies NO, TCAM cancels the entire incoming 
message. Queuing by terminal is required (see the QBY= operand of the 
TERMINAL macro instruction). 

Mid-batch recovery on output requires that LEVEL=BLK be specified, and the 
HOLD macro specifying this operand must be the first macro in the outmessage 
subgroup (LEVEL=BLK may be specified only once in the subgroup). Multiple 
HOLD macros may be coded in the same outmessage subgroup, but other macros 
may not be coded between HOLD macros. If an error mask is specified when 
LEVEL=BLK is coded, the CONNECT=OR operand must be specified. The 
LEVEL=BLK does not apply to a station entering or accepting messages in lock 
mode. 



t 
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INITIATE 



The INITIATE macro 

• sends message segments to their destination as soon as possible after they are 
received at the destination queue; 

• is optional in an inheader subgroup of an MH. 

The INITIATE macro sends the segments of a message from a destination queue 
to their destination as soon as possible after they are placed on the queue. Usual- 
ly, segments are not sent to the destination until the complete message has been 
placed on the queue. Messages sent by segment are transmitted in initiate mode. 
(For information on when messages destined for stations on the same line are sent 
out relative to each other, see Message Priority and Queuing in the chapter 
Defining Terminal and Line Control Areas .) The destination may be either a 
station represented by a single or group entry in the terminal table, or an applica- 
tion program represented by a process entry in the terminal table. This function 
may be performed conditionally, based on the appearance of a specified character 
in the message header, or it may be performed unconditionally. 

When the first segment of a message processed by INITIATE arrives on a destina- 
tion queue, it is treated as if it were a complete message having the highest priority 
on the queue. If the destination queue was created by a TERMINAL macro, as 
soon as a Une to the destination station is available, TCAM begins sending that 
portion of the message that has arrived at the destination queue. No other mes- 
sage may be sent on the line until this entire message has been transmitted. If the 
destination queue was created by a TPROCESS macro, then each message 
segment is sent to the appUcation program as soon as possible after it is enqueued. f 

If a message is sent to a station for which messages are being held (see the de- 
scription of the HOLD macro), the message reverts to normal transmission mode 
rather than remaining in initiate mode. The message is queued on the highest- 
priority queue and is transmitted to its destination after the station is released for 
accepting messages. Once the station is released from its hold condition, TCAM 
resumes transmitting message segments to the destination using the initiate mode 
as described above. 

The function provided by the INITIATE macro might be used as an early notifica- 
tion to a destination station that a very long message is being received by the 
computer, handled, and routed to that destination. 

If a message has multiple destination codes specified in the header, the initiate 
function is performed only for the first destination. Sending to the remaining 
destinations will occur only after the complete message has been placed on the 
destination queue. The initiate function has no effect on a message originated by 
a buffered station or whose destination is a buffered station (TCAM uses normal 
queuing techniques). 

If static deallocation of buffers is specified (that is, if the PCI= operand of the 
line group DCB macro is coded PCI=N and the incoming message contains no 
EOB or ETB control characters), INITIATE gives the message a priority higher 
than that of any other message on the destination queue. 

Messages being sent using initiate mode must fit in the buffers initially allocated 1 

by the BUFOUT= operand of the line group DCB macro when the PCI= operand 
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specifies N or R. If the message can not fit in these buffers, the last byte that does 
fit is considered to be the last byte of the message. 



Name 


Operation 


Operands 


[symbol] 


INITIATE 


[conchars[,BLANK= (char ]]] 

Iyes) 



symbol 



conchars 



(YES 



Function: Name of the macro. 

Default: None. Specif ication optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field to be acted upon, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn' ' 
characters. If hexadecimal format is used, the string must be framed with X' ' or 
XLn* ' characters. 

Notes: If this operand is omitted, the initiate function is performed unconditional- 
ly. If the next field in the header does not match this operand, the function is not 
performed. 



Function: Specifies whether an EBCDIC blank or another character is to be ignored 
when encountered in the character string in the message header being compared to 
the string specified by the conchars operand, or whether blanks are to be part of 
the header string when encountered in it. If EBCDIC blanks are to be counted as 
part of the header string, this operand also specifies whether some other hexadeci- 
mal character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 
Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK=YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 
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NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, like any other character. 

Example: 

INITIATE C £' 

causes the INITIATE function to be executed whenever the & character appears 
as the next nonblank character in the message header. 

In the case of multisegment headers the initiate function must apply to the first 
segment of the message. This is ensured by designing the message header so that 
the control characters appear in the first segment. 
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LOCK 



The LOCK macro 



• connects one station on a line to an application program to await the response 
to an inquiry message entered by the station; 

• holds the connection for a single message or for an extended period; 

• is optional in an inheader subgroup (and not permitted in any other); 

• is required for audio terminals. 

• is suggested for a 3735 attached to a switched line. 

LOCK keeps the connection between a station and an application program, as 
specified in a message header or by a FORWARD macro, for a period of time not 
less than the duration of a message and its response. A station connected in this 
manner is said to be in lock mode . The appUcation program to which a station is 
locked depends upon the destination specified either in the header or by a 
FORWARD macro. If the destination is not an application program, the station 
is not placed in lock mode. 

LOCK does not execute if the station that entered the message being handled is a 
buffered station whose TERMINAL macro specified a buffer delay (by the 
BFDELAY= operand). In this case, a return code of X*00000004' is passed in 
register 15 by TCAM's lock routine. 

The use of this macro with logical messages is restricted to an incoming logical 
message formed by blocking two or more incoming physical transmissions (see 
Handling Logical Messages in this chapter). 

For a description of the lock function, see TCAM's Inquiry /Response Facilities 
in the chapter Writing TC AM -Compatible Application Programs . 

LOCK has the following format: 



Name 


Operation 


Operands 


[symbol] 


LOCK 


(extend \ [,conchars [,BLANK=( YES )]] 

(message/ {^^ \ 

( char ) 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



(extend 1 

|MESSAGEj 



Function: Specifies the type of lock mode required. 

Default: MESSAGE 

Format: EXTEND or MESSAGE. 

Notes: EXTEND specifies that the station transmitting the message is to be 

placed in lock mode until it has no more messages to transmit or until an 

UNLOCK macro is executed. 
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MESSAGE specifies that the station transmitting the message is to be placed in 
lock mode for the duration of the message and its response, and that the Une is to 
be freed once the response has been sent. 



Function: Specifies the character or character string that, if found in the header as 

the next nonblank field, causes execution of the function. 

Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 

character format is used, the string may be unframed or framed with C* ' or CLn' ' 

characters. If hexadecimal format is used, the string must be framed with X* ' or 

XLn* ' characters. 

Notes: If this operand is omitted, the lock function is performed unconditionally. 

If the next field in the header does not match this operand, the function is not 

performed. 

For a station in extended lock mode, control characters are meaningful only for 
the header of the message being processed at the time the station is placed in lock 
mode. The LOCK macro does not examine headers for control characters in 
messages entered by a station already in extended lock mode. 



BLANK=(YES 

NO 
'char 



Function: Indicates whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header that is being compared 
to the string specified by the conchars operand, or whether blanks are to be part 
of the header string when encountered in it. If EBCDIC blanks are to be counted 
as part of the header string, this operand also specifies whether some other 
hexadecimal character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C* ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X* ' or XLT ' characters. 

Notes: This operand is ignored unless the conchars operand is also specified. YES 
specifies that the EBCDIC blank character (X*40') is to be ignored by this macro 
whenever it is encountered in the header character string being checked against 
the control character string specified by the conchars operand. For example, if 
BLANK= YES and an eight-byte field in the header is being checked by this 
macro, a blank appearing in the fifth byte of the field will be ignored and the sixth 
through ninth bytes will be considered to be the last four bytes of the field 
(assuming that no blanks are coded in the sixth through ninth bytes). 



/I 
4 



NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 



char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 



{ 
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encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, like any other character. 

Note: For a station in extended lock mode, control characters are meaning- 
ful only in the header of the message being processed at the time that the 
station is placed in lock mode. The LOCK macro does not examine the 
headers for control characters in messages entered by a station already in 
extended lock mode. 
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LOCOPT 



symbol 



opfield 



The LOCOPT macro 

• provides access to fields in the option table; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups 
(and not permitted in any other). 

LOCOPT enables the user to obtain the address of any option field for the 
appropriate terminal table entry. The address of the desired field or a not-found 
indicator is placed in a user-specified register. A user-written routine may then 
examine and modify the contents of the option field. If specified in the incoming 
group, LOCOPT locates option fields for the originating station; if specified in the 
outgoing group, LOCOPT locates option fields for the destination station. If 
specified in an MH handling messages to or from an application program, 
LOCOPT locates the option fields in the process entry for the queue to which the 
GET or READ is directed (if LOCOPT is issued in the outgoing group), or the 
fields in the process entry for the queue to which the PUT or WRITE is directed 
(if LOCOPT is issued in the incoming group). LOCOPT may be used only for 
option fields for stations or application programs using the MH in which 
LOCOPT is issued. 



Name 


Operation 


Operands 


[symbol] 


LOCOPT 


opfield, i (register) ) 
1(15) f 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the option field whose address is desired. 
Default: None. This operand must be specified. 

Format: Must be the name of an option field as defined by an OPTION macro. 
Notes: If the option field is not found, LOCOPT does not execute, a X*04' return 
code is set in register 15, and the specified register will contain a XTF'. If the 
default register 15 is used and the option field address cannot be located, 
register 15 will contain a fuUword of zeros on return. 



I (register) \ 

(05) S 



Function: Specifies the register into which the address of the desired option field is 

to be placed. 

Default: (15) 

Format: A decimal register 2 through 11, or 15, enclosed in parentheses. 



i 
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LOG 



The LOG macro 

• enables the user to log complete messages or message segments; 

• is optional in any subgroup of an MH. 

LOG enables the user to maintain a record of incoming or outgoing message 
traffic on a sequential medium. Message segments or full messages, as determined 
by the placement of LOG macros in an MH, are placed on an output device. If 
logging is for both message segments and complete messages in the same MCP, a 
data control block must be provided for each function. The various types of logs, 
and the corresponding MH subgroups in which LOG appears are: 

1. Either entire incoming physical transmissions, individual logical messages, or 
portions of individual logical messages (inblock), 

2. Incoming header segments only (inheader), 

3. All incoming segments (inbuffer), 

4. Complete incoming messages (inmessage), 

5. Outgoing header segments only (outheader), 

6. All outgoing segments (outbuffer), 

7. Complete outgoing messages (outmessage). 

When LOG is specified in an inblock subgroup, its position relative to the 
SETEOM macro determines what is logged. If LOG appears before SETEOM, 
TCAM logs the entire incoming physical transmission by segment. If LOG 
appears after SETEOM, either individual logical messages or portions of individu- 
al logical messages are logged, depending on whether deblocking or blocking 
operations are being performed. For deblocking operations, individual logical 
messages are logged (requires that PROCESS = YES be specified on SETEOM). 
For blocking operations, portions of individual logical messages are logged 
(requires that PROCESS = NO be specified on SETEOM). 

When LOG is specified in an inbuffer or outbuffer subgroup, segments are logged 
in the sequence in which they are handled by the Message Handler. In this case, 
segments of different multisegment messages handled at about the same time are 
likely to be intermixed on the logging medium. When segments are logged, their 
buffer prefixes are logged with them. The 12-byte control area connected with 
each buffer unit is not logged. 

LOG may appear at any point in an MH subgroup in which it is used. However, 
the results of any alteration of segments or messages by macros preceding LOG in 
the subgroup will appear in the log. For example, if LOG is preceded by 
DATETIME, a logged header segment will contain the date or time, as specified in 
DATETIME, depending on the location of the date and time in a multisegment 
message. 

LOG may be specified in any subgroup of an MH and may be used more than 
once in a subgroup if desired. The message log may be maintained on any avail- 
able output medium. The user must supply, define, and open the message log data 
sets. For each log data set used to record complete messages, a logtype entry in 
the terminal table must be defined by a LOGTYPE macro (this is not necessary if 
only segments are logged). For information on specifying the message log data 
set, see the chapter Defining the MCP Data Sets . 
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symbol 



When logging segments after a FORWARD macro with multiple destinations, the 
last character of the first destination is overlaid with an unprintable character. 
This byte will be restored at the inmessage subgroup and thus will appear if 
messages are logged. 



Name 


Operation 


Operands 


[symbol] 


LOG 


\ dcbname f 
/ typename ) 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



dcbname 
typename 



Function: Specifies the name of the data control block or the logtype entry used 

for logging. 

Default: None. This operand must be specified. 

Format: dcbname or typename. dcbname is the name of the data control block 

for the message log data set and is used if the macro is specified in the inheader, 

inbuffer, outheader or outbuffer subgroup, typename is the name of a logtype 

entry in the terminal table and is used if the macro is specified in the inmessage or 

outmessage subgroup. 

Notes: If dcbname is specified and does not match the name of a vaHd data 

control block, or if typename is specified and does not match the name of a 

logtype entry in the terminal table, the LOG macro does not execute, and a return 

code of X'04' is set in the low-order byte of register 15. 



i 
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MHGET 



The MHGET macro 



• transfers the contents of the current buffer into a user specified work area or; 

• gives the user the address of the data in the current buffer. 

MHGET may be issued in the inheader or inbuffer subgroup of an MH or in 
serially reusable, user- written open or closed subroutines called in those sub- 
groups. The work area is a part of the MH or the called subroutine and should not 
be confused with an appUcation program work area. MHGET does not affect or 
depend on any functional macros used in the MH or subroutine. Therefore, any 
order of functional macros and MHGET will work. MHGET may be specified 
either to return the address of the first data character in the buffer or to move the 
entire data contents of the buffer into a user-specified work area. The amount of 
data moved will be the entire message or as much of the message as will fit into 
the user-specified work area. The MHGET macro will move data from multiple 
buffers into the work area consecutively, if the length of the data previously 
moved in is left in the DATLEN field of the work area prefix. If the work area is 
to contain only the data from a single buffer, the DATLEN field should be zeroed 
by the user before issuing the MHGET macro. 

The format of the work area is: 



WKLEN 
1 


DATLEN 

2 3 


PRFSTAT 

4 


UNRES 

5 


DATA 
6-n 



Bytes Field 

Name 



Description 



- 1 WKLEN 



User-supplied data length of the work area (does 
not include the six-byte work area prefix length). 



2 - 3 DATLEN 



Length of data moved, supplied by MHGET on return 
to the user. The user must zero this field before 
issuing a single-buffer MHGET or the first MHGET 
of a series of multiple-buffer MHGETs. For the 
second and subsequent MHGETs, when moving the data 
from multiple buffers consecutively into a single 
work area, this field must contain the data length 
put there by the previous MHGET. 



PRFSTAT 



The status byte from the buffer prefix indicating: 



X'OO' Header lost 

X'Or Text lost 

X'OT Header not lost 

X'03' Text (not header) not lost 

X'08' Duplicate header 



> 



5 UNRES 

6-n Data 



The number of unused reserve characters. 



The first to nth data characters in the buffer. 
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MHGET will supply the following return codes in register 1 5 

00 MHGET successful - no errors 

04 Data moved; work area too small; data truncated 

08 TCAM not in system 

OC Empty buffer-no user processing permitted 

MHGET has the following format: 



Name 


Operation 


Operands 


[symbol] 


MHGET 


(W0RK= jregister)) [,RESERVES= rYES )] 
) \name jV |NO j 
pEG=f(register)) I 
V (name j / 



symbol 



WORK=((registerA 
(^ name f 



REG= 



Reregister) 1 
(^ name j 



RESERVES=JYES> 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Points to the user-supplied work area. 

Default: None, (register) or name must be specified. 

Format: ( register ) may be the actual register number, name is the name of a 

work area or may be an equated name of a register. Registers 2 through 12 may 

be used. 



Function: Returns the address of the first data character in the buffer in the 
specified register. The specified register is the lower of a pair of consecutive 
registers. The next higher register will contain the following: 

byte Zero 

byte 1 Buffer status (PRFSTAT 1 ) 

bytes 2-3 Length of the data in the buffer 

Default: None. Must be specified if WORK= operand is not specified. 

Format: ( register ) may be the actual register number. 

name may be an equated name of a register. Registers 2 through 1 1 may be used. 

Function: Move unused reserve spaces into the work area in front of the data. The 
number unused will be put into the UNRES field of the work area header. 
Default: No. 
Format: RESERVES= YES or RESERVES=NO. 






i 
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MHPUT 



The MHPUT macro 



• transfers the contents of a user-specified work area into the current buffer; 

• resets the scan pointer to the beginning of data in the buffer. 

MHPUT may be issued in the inheader or inbuf f er subgroup of an MH or in 
serially reusable, user- written open or closed subroutines called in those sub- 
groups. MHPUT will transfer whatever is in the user-specified work area into the 
current buffer leaving room for the unused DCB or user-specified reserve charac- 
ters. Up to 65,535 (XTFFF') characters may be written, and the routine will set 
up the maximum number of units per buffer to contain the data. Care should be 
taken that data in the header that subsequent functional macros will need is not 
destroyed or overlaid by execution of the MHPUT macro. Since MHPUT sets the 
scan pointer to the beginning of data in the buffer, before issuing a macro that 
uses the scan pointer, the user should be certain that the scan pointer is properly 
set for that macro. If these precautions are observed, MHPUT does not affect or 
depend on any functional macros, any order of functional macros, and MHPUT 
will work. If PCI=A and EOB checking are used in conjunction with 
MHGET and an input data error occurs, it is possible that some of the data may 
be processed before it is known to be bad. If MHPUT is also unused, it is possible 
that data processed prior to EOB checking may be destoryed by the error recovery 
procedures. These two conditions will be avoided if PCI=X is coded and mid-batch 
recovery is not used. 

Note: The MH prefix of MHGET and MHPUT specifies that the macros 
are to be used in a message handler as opposed to GET and PUT macros 
for an application program. The function of MHGET is to transfer the 
contents of the current buffer into a user specified work area. The function 
of MHPUT is to transfer the contents of a user specified work area into the 
current buffer. The implication is that these macros may be used to perform 
intermediate operations on messages before they are passed on to an applica- 
tion program or to an output destination buffer. The flow might be 



MHGET 



MHGET 



process or process 

MHPUT FORWARD 

The format of the work area is: 



Unused 
1 


DATLEN 

2 3 


Reserved 
4 5 


Data 
6-n 



Bytes 



Field 
Name 



Description 



0- 1 



Unused and unchanged by MHPUT 
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2-3 DATLEN Length of the user-supplied data starting at the 

first position of the data field of the work area. 
Maximum data length can be 65,535 (XTFFF'). 

4-5 Reserved 

6 - n Data User data to be written (MHPUT). 

MHPUT will supply the following return codes in register 15: 

00 MHPUT successful 

04 MHPUT could not allocate enough units; data is truncated. 
This return code is also set when the number of units per 
buffer has reached the maximum. 

08 TCAM not in the system 

10 Length of work area not initiahzed. 

MHPUT has the following format: 



Name 


Operation 


Operands 


[sym-bol] 


MHPUT 


WORK=((register^)[,RESERVE=value] 
( name j 



symbol 



WORK=J(register)) 
I name j 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Provides the name or address of the user's work area. 

Default: None, (register) or name must be specified. 

Format: (register) may be the actual register number, name is the name of a work 

area or may be the equated name of a register. Registers 2 through 12 may be 

used. 



( 
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RESERVE=value 

Function: Allows the user to specify the reserve count. 
Default: None. Specification optional. 
Format: Unframed decimal integers. 
Maximum: 221 

Notes: When this operand is not specified, MHPUT begins transferring the data 
into the header buffer starting at the first position following the unused DCB 
reserves. This operand allows the user to override that specification. If 
RESERVE =0 is specified, MHPUT begins moving data into the buffer beginning 
at the first byte after the buffer prefix. If RESERVE= 1 is specified, MHPUT 
begins moving data into the second byte after the prefix, etc. If the user reserves 
specified are greater than the maximum allowable in the DCB, the maximum 
allowable is used instead of what was specified by this operand and the return 
code X*OC' is placed in register 15. 



Designing the Message Handler 251 



MSGEDIT 



The MSGEDIT macro 

• inserts specified characters at specified locations in a message; 

• deletes specified characters from a message; 

• replaces deleted characters with other characters, or contracts remaining data 
to fill the gap caused by deletion; 

• dynamically allocates buffer units to contain data inserted in message segments; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups, 
and may not be coded in any other subgroup. 

The MSGEDIT macro allows the user to edit incoming and outgoing messages in a 
Message Handler. Each editing operation performed by MSGEDIT falls into one 
of two categories: it is either an insertion or a removal. 

An insert operation is one in which specified characters are inserted at a specified 
point in a message, with no characters being deleted in the operation. The oper- 
ands of MSGEDIT allow characters to be inserted 

• at a single point in a message; 

• at a specified offset from the beginning of each message segment; 

• whenever a certain character string appears in a message; 

• after every n bytes of message data, where fz is a number specified by the user. 

The inserted data may consist of a single character, or a character string, including 
a string of identical characters. If the MSGEDIT macro is issued in an inheader or 
outheader subgroup, the insert operation is performed only for a single segment of 
a message. This is usually the first segment, but may be a subsequent segment if 
the message has a multiple-buffer header and the MSGEDIT macro is issued in a 
portion of the subgroup that is processing header fields in the second or subse- 
quent segments. (The manner in which inheader and outheader subgroups are 
executed for multiple-buffer headers is described in the chapter Designing the 
Message Handler .) If the MSGEDIT macro is issued in an inbuffer or outbuffer 
subgroup, the insert operation is performed for each segment in the message. The 
insert function might be used to add a new destination name to the destination 
field in a message header, or to insert idle characters into a message destined for a 
printer that requires such characters to prevent ''printing on the fly" during a 
carriage-return operation. For other uses, see the examples below. If the insert 
function is for a character string that may cross buffer boundaries, MSGEDIT 
should be coded in the inblock subgroup. 

A remove operation is one in which a specified character string is removed from a 
message. The user may specify that the character string be replaced with another 
character string, or that the remaining data be contracted to fill the gap left by the 
deleted data. The user may remove 

• a single character string; 

• a specified character string whenever it appears; 

• a specified number of bytes of data whenever a certain character string ap- 
pears; 

• the data located in a specified section of a buffer. 

In any of the above cases, the user may replace the deleted data with other data, 
or he may specify that data following the deleted data in a message segment be 
moved left to fill the gap left by the deleted data. If a substituted character string 
is longer or shorter than the deleted character string, TCAM automatically spreads 
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or contracts the data remaining in the buffer to ''fit" the new string; buffer units 
are allocated as needed to accommodate the new data. If MSGEDIT is coded in 
an inheader or outheader subgroup, data is removed from only a single header 
segment of a message. If MSGEDIT is coded in an inbuffer or outbuffer sub- 
group, data is removed from all message segments. The remove function might be 
used to delete a destination from the destination field in the message header, to 
substitute one destination name for another in the header, to remove unnecessary 
data from an outward-bound message, or to replace a specified character with a 
logical-record delimiter that is recognized by application-program GET macros. 

If the buffer containing a message segment is not long enough to accommodate 
additional data inserted by a MSGEDIT macro, more buffer units are automatical- 
ly added to the buffer. Because of internal requirements, for insert operations 
MSGEDIT automatically allocates a minimum of one buffer unit before execution. 
This unit, whether it eventually contains data or not, remains with the buffer. 
This fact should be considered when determining the unit count for the MCP. 
The effect of this automatic unit allocation can be diminished by the use of the 
multiple — operand feature of the MSGEDIT macro. Empty units at the end of a 
buffer are automatically deallocated when the buffer is passed to an INMSG or 
OUTMSG macro; deallocated units are returned to the available-unit queue. 

If the remove function is for a character string that may cross buffer boundaries, 
MSGEDIT should be coded in the inblock subgroup. 

Up to 3 1 separate insert and remove operations may be specified by issuing a 
single MSGEDIT macro having up to 31 groups of positional operands. Since any 
operation that can be performed with multiple groups of operands also can be 
performed with a single group, then only one group of operands is allowed in the 
same MSGEDIT macro. Assembler language restrictions on the length of a macro 
operand apply. 

The MSGEDIT macro operand field consists of from one to 3 1 groups of four 
operands each and a single keyword operand that is coded as the last operand of 
the macro. Each group of positional operands is enclosed in parentheses, and 
each specifies a single insert or remove operation (which may, however, entail 
multiple insertions or deletions). If the user wishes to perform many insert or 
remove operations on his messages, he may either code a single MSGEDIT macro 
having many groups, or he may code several MSGEDIT macros, each performing 
one or two insert or remove operations. 

A single MSGEDIT macro with five groups executes more rapidly than would five 
MSGEDIT macros, each having one of the groups. However, certain restrictions 
that apply to a MSGEDIT macro having several groups are not applicable when 
several MSGEDIT macros having one group each are used instead (these restric- 
tions are discussed below in the description of the MSGEDIT operands). Thus, 
the decision of whether to code one MSGEDIT macro or whether to code several 
depends on which is more important — speed of execution or flexibility. 

Each group contains an AT operand, which specifies where, in a buffer, an insert 
or remove operation is to begin. The order in which operations are performed 
depends upon the relative locations of the character strings specified by the AT 
operand in each group. The function specified by the group whose AT operand 
appears first in a particular message segment is performed first for that segment, 
the function specified by the group whose AT operand appears second is per- 
formed second, etc. 
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When multiple groups of positional operands are coded for a MSGEDIT macro, 
rather than multiple MSGEDIT macros each with a single group, data inserted by 
one operation is not considered to be part of the message segment when another 
operation is being performed. For example, if one group caused a B character to 
be inserted after every A character in the message, and another group of the same 
MSGEDIT macro specified that a C character be inserted after every B character 
in the message, no C character would be inserted after a B character that had itself 
been inserted as a result of an A character having been encountered in the mes- 
sage segment by the MSGEDIT macro. 

Insertion or removal of data using a MSGEDIT macro always results in a move- 
ment of data in the buffer. Even when a MSGEDIT macro specifies only a single 
remove operation and the replacement string is equal in length to the character 
string being replaced, movement of data occurs (though in this case the result of 
the data movement would be that the replacement string would be moved into the 
space originally occupied by the deleted string). As a rule, when a MSGEDIT 
macro operates on any data in a buffer, all of the data between the characters 
affected by the first insert or remove operation and the end of the buffer is shifted 
once by MVC instructions issued internally by TCAM. 

When coded in an inblock subgroup, the MSGEDIT macro can be used to remove 
or replace a character string that extends across message segments and buffer 
boundaries. See the description of the inblock subgroup in Structure of the 
Message Handler. 

The MSGEDIT macro has certain Hmitations: 

1. When issued in an inheader or outheader subgroup, MSGEDIT acts only upon 
one header segment of messages having multiple-buffer headers. The segment 
acted upon is the one being processed by the inheader or outheader subgroup at 
the time MSGEDIT is executed. Moreover, a MSGEDIT macro issued in an 
inheader or outheader subgroup assumes that the header occupies the entire 
segment being operated upon. Thus, if a MSGEDIT macro in an inheader 
subgroup .specifies that NYC is to replace BOS whenever the latter character 
string occurs in the header, and if the header ends midway through the first 
message segment, BOS will be replaced if it appears in the second half of the 
segment, even though it is outside of the header. 

2. Any character string in an operand specified in character format rather than as 
hexadecimal data cannot include a comma or a right parenthesis. If the charac- 
ter field requires the use of these characters, the field must be specified in 
hexadecimal format. 

3. The user must beware of performing message editing functions that either add 
or remove data to the left of the scan pointer while he is performing sequential 
processing of header fields. Because the scan pointer is positioned at a particu- 
lar physical location in the buffer, rather than at a particular character, addition 
of data to the left of the scan pointer results in the shifting of the original scan 
pointer to the left. The following example illustrates the possible problem 
resulting from improper placement of a MSGEDIT macro in the Message 
Handler: 

SETSCAN C'X' 

ORIGIN 5 

MSGEDIT ( ( I , C' INSERT ' , 1 ) ) 

FORWARD DEST=5,E0A=* 
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After the SETSCAN and the ORIGIN macros are executed, the buffer might look 
like this: 

prefix X TERMA TERMB TERMC * message data 

f 

scan pointer 



After the MSGEDIT macro executes, the buffer looks like this: 

prefix INSERT X TERMA TERMB TERMC * message 

t . 

scan pomter 

When the FORWARD macro executes, the origin (TERMA) will be considered to 
be the first destination (TERMB.) To avoid such problems, the user may follow 
these two guidelines: 

1. Perform as many of the functions of MSGEDIT as possible in an INBUF or 
OUTBUF subgroup rather than in INHDR or OUTHDR. 

2. Perform all functions of MSGEDIT that affect header fields either before all 
sequential processing of header fields begins, or after all sequential processing 
of header fields has been completed. Examples are: 

a. MSGEDIT ( ( I , C ' INSERT ' , 1 ) ) 
SETSCANC'X' 

ORIGINS 

FORWARD DEST=5 , EOA-* 

b. SETSCAN C'X' 
ORIGINS 

FORWARD DEST-S , EOA=* 
MSGEDIT ( ( I , C ' INSERT ' , 1 ) ) 

MSGEDIT moves the scan pointer backwards for the user for one special case. 
This is a remove (or replace) function specifying the scan pointer itself as the TO 
operand. Examples of this are: 

MSGEDIT ( ( R, , 2S , SCAN ) ) 

MSGEDIT ( (R,C' INSERT' ,2S,SCAN) ) 

In these examples, if the remove or replace function results in the deletion of more 
bytes than exist between the scan pointer and the end of data in the buffer after 
the macro executed, the scan pointer would, if not adjusted, erroneously point 
beyond the end of the data in the buffer and prevent any subsequent sequential 
processing. Therefore, in these cases, the scan pointer is moved backward a 
distance equal to: 

a. the length of the data removed,or 

b. the length of data removed less the length of data inserted. 

The user is cautioned that he may have to read the following description several 
times before he understands how to code the macro. Several examples follow the 
macro description. 

MSGEDIT has the following format: 



Name 


Operation 


Operands 


[symbol] 


MSGEDIT 


((groupl),(group2),...)[,BLANK= (NO )] 

<^charj> 

(yes) 
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symbol 



((groupl),(group2),...) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Each group specifies a single insert or remove function. 

Default: None. At least one group must be specified. 

Format: Each group contains (function,data,AT,TO) operands. They must be 

provided in the order shown, enclosed in parentheses, and separated from each 

other by a comma. 

Maximum: A maximum of 31 groups may be coded. 

Notes: Because of the complexity of the macro, the operands are explained 

individually below. 

The structure of each group of positional operands is as follows: 



Function operand 


Data operand 


AT operand 


TO operand 


JR[A][T]( 




characters 
(hexform,n) 

DELIMIT 
CONTRACT 






characters 

offset 

(integer,optfield) 

SCAN 




characters 
offset 

SCAN 
(count) 

m J 


,... 


L- -1 







function operand 
I R[A][T] , 



luiiciiuii vptri 

|r[AMT]| 



Function: Specifies whether an insert or remove function is to be performed and, 

if a remove function, whether the characters delimiting the beginning and the end 

of removal are themselves to be removed. 

Default: None. This operand must be specified. 

Format: I, R, RA, RT, RAT, or RTA. 

Notes: I specifies that an insertion function is to be performed. The data specified 

in the data operand is the data inserted in the message. 



R specifies that a remove function is to be performed; any data specified by the 
AT operand and the TO operand is to be removed from the message and replaced 
with the data specified by the data operand. If no data is specified by the AT 
operand or by the TO operand MSGEDIT removes one byte of data beginning at 
the location currently designated by the scan pointer. If no data is specified by 
the data operand, data that remains in a buffer after deletion is contracted to fill 
the space left by the removed data. 



A specifies that removal is to begin with the first character of the character string 
specified in the AT operand; in this case, if replacement data is specified in the 
data operand, the first byte of replacement data is inserted in the space occupied 
originally by the first byte of the character string specified by the AT operand. If 
A is omitted, removal and replacement begin with the character immediately 
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data operand 

r characters 

(hexform,ii) 

DELIMIT 

LCONTRACT. 



following the last character in the string specified in the AT operand. If A is 
coded in a group, a character string should be coded as the AT operand; other- 
wise, MSGEDIT removes one byte of data beginning at the location currently 
designated by the scan pointer and proceeds to the next group, if any, to accom- 
pUsh the next insert or remove function. 

T specifies that removal is to end with the last character of the string specified in 
the TO operand; if T is not coded, the character immediately preceding the first 
character of the string specified by the TO operand is the last character removed. 
If T is coded in a group, a character string should be specified as the TO operand; 
otherwise, MSGEDIT removes one byte of data beginning at the location current- 
ly designated by the scan pointer and proceeds to the next group, if any, to 
accomplish the next insert or remove function. 



Function: If this is an insert function, specifies the data to be inserted in the mes- 
sage. If this is a remove function, specifies either the data to replace the charac- 
ters removed from the message or specifies that the data remaining in a buffer 
after deletion is to be contracted to fill the space originally occupied by the 
deleted data. 
Default: CONTRACT 

Format: characters, (hexform,n), DELIMIT, or CONTRACT, characters may be 
one to eight nonblank characters in character or hexadecimal format. If character 
format is used, framing C ' or CLn' ' characters must be used. If hexadecimal 
format is used, framing X' ' or XLn' ' characters must be specified. 

(hexform.n) must be coded within parentheses, hexform is a single character in 
hexadecimal or character format surrounded by framing X' ' or C ' characters, n 
is a decimal integer and must not be framed. 
Maximum: n may be a maximum of one buffer unit. 
Notes: characters in an insert operation specifies the character string to be 
inserted into the message. In a remove operation, characters specifies the charac- 
ter string that is to replace the deleted data. If messages are to be translated, 
inserted characters should be in EBCDIC; if they are not to be translated, inserted 
characters should be in terminal transmission code. 



(hexform,n) specifies that the single character represented by hexform is to be 
inserted the number of times indicated by n . The inserted characters will be 
contiguous; if this is a remove operation, they will replace the deleted data. This 
operand may be used to insert idle characters in outgoing messages. 

DELIMIT is valid only if the function operand specifies a remove function. 
DELIMIT specifies that the character in the RECDEL= operand of the 
TPROCESS macro whose name is entered as the destination of this message is to 
replace the character string delimited by the AT and TO operands. This character 
is recognized by the application program's GET macro as the delimiter of a 
variable-length record. The MSGEDIT macro in which this operand is coded is 
usually located in the outbuffer subgroup of the MH for the appUcation program 
or in the inbuffer subgroup for the line over which the message is received. If 
MSGEDIT is located in an inheader subgroup, only a single header segment is 
scanned for the character to be replaced. The destination queue must be identi- 
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AT operand 
"characters 

offset 

(mteger,opfield) 

LSCAN 



fied by means of a FORWARD macro before the MSGEDIT macro is issued. If 
the destination of this message is not an application program, the MSGEDIT 
group containing DELIMIT does not execute. 

CONTRACT is vahd only if the function operand specifies a remove function. 
CONTRACT specifies that after the appropriate data has been deleted from a 
message segment, succeeding characters in the buffer are to be moved to overlay 
deleted characters. If contraction results in one or more empty units at the end of 
the buffer, these are released when the segment leaves the incoming or outgoing 
group of the MH. 

If the function operand specifies an insert function and if CONTRACT is coded 
(or if the data operand is omitted), this MSGEDIT macro does not execute, and 
control passes to the next instruction in the MH. 



Function: If an insert function is being performed, specifies the location at which 

the insertion is to be made. If a remove function is being performed, specifies the 

location of the beginning of the string to be removed. 

Default: SCAN 

Format: characters, offset, (integer,opfield), or SCAN. 

characters specifies one to eight nonblank characters in either character or hexade- 
cimal format. If character format is used, the string must be framed with C ' or 
CLn' ' characters. If hexadecimal format is used, the string must be framed with 
X' ' or XLn' ' characters, offset is a decimal integer specified without framing 
characters. 



(integer.opfield) must be coded within framing parentheses, integer may be 
specified either in decimal or hexadecimal format. If hexadecimal format is used, 
the value must be coded within framing X* ' or XLn' ' characters, opfield is the 
name of a halfword option field defined by an OPTION macro. 
Maximum: For offset , 65535. For integer , 65535, or a hexadecimal field of two 
bytes. 

Notes: If this is an insert function, characters specifies a string immediately 
following which the data specified in the data operand is to be inserted. If the 
MSGEDIT macro is included in an inheader or outheader subgroup, the specified 
data is inserted each time this string is encountered in the message header. If the 
MSGEDIT macro is issued in an inbuffer or outbuffer subgroup, the specified data 
is inserted each time this string is encountered anywhere in the message. 

If this is a remove function, characters specifies a string that delimits the begin- 
ning of the data to be removed. If the A suboperand of the function operand is 
included, removal begins with the first character of this string; if A is not included, 
removal begins with the character immediately following the last character of this 
string. If A is coded in the function operand and the TO operand is coded (0) or is 
omitted, only the string specified in the AT operand is removed. If the MSGEDIT 
macro is included in an inheader or outheader subgroup, removal occurs each time 
the character string is encountered in the message header. If the macro is issued in 
an inbuffer or outbuffer subgroup, removal occurs each time the character string is 
encountered in the message. 
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TO operand 
"characters" 
offset 

SCAN 
(count) 

LiO) 



If characters is coded, either characters or (count) should be specified as the TO 
operand. If SCAN is specified as the TO operand, TCAM assumes a count of zero 
has been specified for TO. If an offset is specified for the TO operand, TCAM 
assumes that the offset is a count. 

If characters is coded, the entire string must be located within a single buffer. If 
more than one group of operands is included in this macro, the AT operand for 
each group must be specified as characters , and each character string specified as 
an AT operand must begin with a different character. 

If this is an insert function, offset specifies the number of bytes beyond the buffer 
prefix immediately following which the first character specified in the data oper- 
and is to be inserted. If this is a remove function, offset specifies the number of 
bytes beyond the prefix immediately following which deletion of data is to begin. 

If the MSGEDIT macro is specified in an inheader or outheader subgroup, offset 
applies to a single header segment only, and insertion or deletion of data occurs 
only once. If the macro is coded in an inbuffer or outbuffer subgroup, data is 
inserted or deleted at the specified offset in every segment of the message. If this 
is an insert operation and an offset of 2 is specified, the first character inserted 
will immediately follow the contents of the second byte beyond the buffer prefix. 
If this is a remove function and an offset of 2 is specified, the first byte whose 
contents are removed from a segment will be the third byte beyond the buffer 
prefix. 

(integer,opfield) specifies that the data coded for the data operand is to be inserted 
after every number of bytes specified by integer. If integer is 20, for instance, the 
data specified in the data operand is inserted after every 20 bytes of message. An 
integer greater than 1 may not be specified if the source station (when MSGEDIT 
appears in the inbuffer or inblock subgroup) or the destination station (when 
MSGEDIT appears in an outbuffer subgroup) uses the block checking feature for 
a message. When insertion does occur, however, it occurs in both the header and 
text, opfield is the name of an option field assigned to the origin (if MSGEDIT is 
coded in the incoming group) or to the destination (if MSGEDIT is coded in the 
outgoing group). The option field must be initialized by the OPDATA= operand 
of the TERMINAL or TPROCESS macro (it may be set to a half word of zero). 
(integer, op field) coded as the AT operand has the following restrictions: 

• I must be coded as the function operand; 

• this MSGEDIT macro may be coded in an inbuffer or outbuffer subgroup only; 

• only one group of positional operands may be specified; 

• characters or (hexform^n) must be specified for the data operand. 

SCAN specifies that insertion or deletion is to begin with the character immedi- 
ately following the byte to which the scan pointer is currently pointing (see the 
description of the scan pointer in Z)e5/gAZ/«g the Message Handler). This oper- 
and may be specified only when the macro is issued in an inheader or outheader 
subgroup. 



Function: For remove functions only, specifies the end of the character string to 
be deleted. 
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Default: (0) 

Format: characters, offset, SCAN, (count) or (0). characters specifies a one- to 
eight-byte field in either character or hexadecimal format. If character format is 
used, framing C* ' or CLn' ' characters must be specified. If hexadecimal format is 
used, framing X* ' or XLn' ' characters must be specified, offset specifies a 
decimal integer coded without framing characters, (count) must be coded within 
its framing parentheses and is a decimal integer specified without framing charac- 
ters. 

Maximum: Both offset and (count) have a maximum value of 65535. 
Notes: characters indicates the location of the last character to be deleted. If the 
T suboperand of the function operand is coded, deletion ends with the last charac- 
ter of the string specified here; otherwise, deletion ends with the character imme- 
diately preceding the first character of the string. The entire string must be 
located in the buffer that contains the delimiter specified by the AT operand, since 
deletion must begin and end in the same buffer. If both the AT and the TO 
operand specify character strings, TCAM assumes that the first byte of the TO 
string is to the right of the last byte of the AT string. 

offset specifies an offset from the beginning of the data in a message segment; this 
offset defines the end of the string to be deleted in this operation. If the offset is 
20, for instance, the character occupying the twentieth byte from the beginning of 
data in the buffer is the last character deleted. The offset must specify a byte that 
is in the same buffer as, and either in the same position as or to the right of the 
first byte of data removed (as specified by the AT operand); each deletion must 
begin and end in the same buffer. If the offset specified by the TO operand is 
identical with the offset specified by the AT operand, the single character located 
at this offset is removed. If the offset is beyond the end of the buffer, data will be 
deleted to the end of the buffer. 

If this MSGEDIT macro is specified in an inheader or outheader subgroup, offset 
applies to a single header segment only and deletion occurs only once. If the 
macro is coded in an inbuffer or outbuffer subgroup, data is deleted from each 
segment. 

SCAN specifies that the character indicated by the current position of the scan 
pointer is to be the last character deleted in this remove operation. This operand 
may be coded only in a MSGEDIT macro issued in an inheader or outheader 
subgroup. If SCAN is coded for both the AT and the TO operand, and R is 
specified in the function operand, the single character located at the current 
position of the scan pointer is deleted. 

(count) and its default value (0) specify the number of bytes of data to be deleted, 
starting with the byte immediately following the AT operand. If the AT delimiter 
is a character string and if A is coded in the function operand, the amount of data 
removed is equal to the sum of the number of characters in the AT delimiter string 
plus the number of bytes specified by (count) . If the integer specified by (count) 
is greater than the number of bytes between the AT delimiter and the end of the 
buffer, all characters between the AT delimiter and the end of the buffer are 
deleted. A count of zero indicates that no data is to be deleted (except for the 
characters in the AT delimiter if A is coded in the function operand); if the TO 
operand is omitted, a count of is assumed. If A is coded in the function operand 
and a string is coded in the AT operand, the string is removed each time it is 
encountered if (0) is coded or if no TO operand is specified. 
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BLANK=rchar 

/yes 



Function: This operand specifies whether EBCDIC blank characters are to be 
ignored when encountered in searching the message for a field, or whether blanks 
are to be considered part of the field when encountered. If EBCDIC blanks are to 
be counted when found, this operand also specifies whether some other hexadeci- 
mal character is to be ignored when encountered in searching the message for a 
field. 

Defauli: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 
Notes: YES specifies that the EBCDIC blank character (X'40') is to be ignored 
by this macro whenever it is encountered in a message. For example, if 
BLANK=YES is coded and an eight-byte field is being acted upon by this macro, 
a blank appearing in the fifth will be ignored and the sixth through ninth bytes will 
be considered to be the last four bytes of the field (assuming that no blanks are 
coded in the sixth through ninth bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the message. 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header. That is, the macro automatically 
skips over the character without checking it. If BLANK = char is coded and char 
is not the EBCDIC blank, the EBCDIC blank is treated Hke any other character. 

With one exception (when both the AT and the TO operands are coded as or with 
SCAN), the first byte of a string of data to be removed, as determined by the AT 
operand, must be to the left of, or in the same position as, the last byte of the 
string of data to be removed, as determined by the TO operand. See the following 
examples. 

The first character in a character string to be deleted, as specified by the AT 
operand, must not be to the right of the last character of the character string, as 
specified by the TO operand. If both operands specify the same byte, that byte 
only is removed. As an example, consider the following initial portion of a buffer, 
with the scan pointer located at D: 



N Y C D R A L 



data 



1 



beginning SCAN 
of data PTR 

A MSGEDIT macro coded 

MSGEDIT ( ( R,CL3'B0S' , SCAN, 4 ) ) 
would result in the character D being replaced with the string BOS in the buffer. 
A MSGEDIT macro coded 
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MSGEDIT ( (R,CL3'B0S' ,CL1 'D' ,CL3'RAL' ) ) 

would result in BOS inserted after D; this macro says to remove the character (| 

between D and R and replace it with BOS. Since there is no character between D 
and R, none is removed, but BOS is still inserted. 

Examples 1 : 

MSGEDIT is a complex macro, capable of performing many functions. In this 
section, some of the more common functions of MSGEDIT are discussed and 
illustrated with examples. 

Insertion of a single character string after a specified field in a header buffer: The 
following MSGEDIT macro might be coded in an inheader subgroup to add the 
destination RAL to the Hst of destinations specified in the message header. 
Assume that the last destination specified in the header is NYC, and that 
DEST=(3) is coded in the FORWARD macro. 

EDIT1 MSGEDIT ( ( I,CL3'RAL' ,CL3'NYC' ) ) 

Note that only the function, data, and AT operands are coded for this macro; the 
TO operand must not be coded for an insert operation. 

Example 2: 

Insertion of a character string after every 50 bytes of message data: The following 
MSGEDIT macro might be coded in the outbuffer subgroup of a Message Handler 
assigned to.an apphcation program to cause the EBCDIC Z character (specified as 
a record delimiter by the RECDEL= operand of the TPROCESS macro creating 
the process entry specified as the destination of the message) to be inserted after /^ 

every 50 bytes of message data. I 

EDIT2 MSGEDIT ( ( I , C ' Z \ ( 50 , EDITOPT ) ) ) 

Note that no TO operand is coded and that only one group is specified. 
EDITOPT is the name of a halfword option field created by an OPTION macro 
and initialized with zeros by the OPDATA= operand of the TPROCESS macro 
creating the process entry specified as the destination of this message. 

Example 3: 

Replacement of one character string in a message with another character string: 
The following MSGEDIT macro is coded in the inheader subgroup; it causes the 
character string BOS to be replaced with the character string OMAHA wherever 
the former string appears in the first segment of the message (remember, however, 
that the entire character string BOS must occur in the segment in order for 
MSGEDIT to operate on it). If a buffer is not long enough to accommodate the 
longer character string, TCAM will automatically allocate extra units to the buffer 
as needed. 

EDIT3 MSGEDIT ( ( RA, CL5 ' OMAHA ' ,CL3'B0S' ) ) 

Note that no TO operand is coded. The A in the function operand specifies that 
the AT character string is to be deleted and that the O in OMAHA is to be 
positioned at the location occupied by the B in BOS. If the TO operand had been 
coded BOS, all data in the segment between the first BOS and a second BOS g 

would be deleted. If the segment contained no second BOS, the remove operation 1 
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would not take place; the macro would not execute, and control would pass to the 
next macro. 

Example 4: 

Insertion and replacement: A single MSGEDIT macro might be issued in an 
inheader subgroup to accomplish the two editing functions described above. This 
macro would cause RAL to be inserted after each NYC in the first segment, and 
would also cause BOS to be replaced with OMAHA each time BOS appeared in 
the first segment. 

EDIT4 MSGEDIT ( ( I , CL3 ' RAL ' , CL3 ' NYC ' ) , 
( RA , CL5 ' OMAHA ' , CL3 ' BOS ' ) ) 

Example 5: 

Deletion and contraction: The following MSGEDIT macro might be issued in the 
inheader or outheader subgroup. It causes the ten bytes immediately following the 
current position of the scan pointer to be deleted; all data following the deleted 
ten bytes in the first message segment is shifted to the left ten spaces to fill in the 
space occupied by the deleted data. The shift may result in an empty unit at the 
end of this buffer; empty units are dynamically deallocated and returned to the 
available unit queue when the buffer leaves the MH group. 

EDITS MSGEDIT ( ( R, , , ( 1 ) ) ) 

Note that the data and AT operands were not coded, since their default values are 
CONTRACT and SCAN, respectively. Figure 20 illustrates how a single buffer 
containing an entire message might look before and after this macro was executed. 
Assume that the units are 64 bytes long, that the buffer consists of two units, and 
that the second unit contains only six bytes of data before the MSGEDIT macro is 
executed. Assume also that all of the ten bytes immediately following the position 
of the scan pointer contain meaningful data (none of the bytes contain blanks). 
Notice that after the deletion was made, all data following the deleted characters 
was moved ten bytes to the left; as a result the second unit contains no meaningful 
data after the remove operation. 

Example 6: 

Insertion of idle characters: The following macro, when coded in an inbuffer or 
outbuffer subgroup, causes 13 EBCDIC idle characters (X'17') to be inserted 
whenever a period is encountered in a message. 

EDIT6 MSGEDIT ( ( I , ( X ' 1 7 ' , 1 3 ) , CL1 ' . ' ) ) 

Example 7: 

Insertion of a record delimiter: The following macro, when coded in an inbuffer 
or outbuffer subgroup, causes the logical record delimiter X to be substituted for 
the character D wherever the latter character appears in a message. The X 
delimiting character, which would be coded in the RECDEL= operand of a 
TPROCESS macro, is considered by a GET command issued by an application 
program to be the delimiter of a logical record. 

EDIT7 MSGEDIT ( ( RA, DELIMIT, CL1 'D' ) ) 

Example 8: 

Miscellaneous examples: The following MSGEDIT macro, when coded in an 
inbuffer or outbuffer subgroup, causes the character string OUT and the ten 
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Figure 20. Deletion of Data from a Message Segment followed by Contraction of the Segment; KEYLEN=60 and BUFSIZE= 120 

characters immediately following OUT to be removed from a message segment 
wherever OUT appears in a segment. Data following the 13 deleted characters is 
moved to the left to fill the gap caused by the deletion. EBCDIC blanks are 
counted as characters in this example. 

EDITS MSGEDIT ( ( RA, CONTRACT , CL3 ' OUT ' ,( 10 ) ) ) , BLANK=NO 

The following MSGEDIT macro, when coded in an inbuffer or outbuffer subgroup 
causes the data between every R character and E character to be replaced with the 
character string EPLAC. If the data being deleted occupies less space than the 
replacement string, the data in the buffer is automatically spread out to make 
room for the insertion, and another buffer unit is added to the buffer if necessary. 
If the data being deleted occupies more space than the replacement string, data to 
the right of the replacement string is automatically moved to the left to fill the gap. 

EDIT9 MSGEDIT ( ( R, CL5 ' EPLAC ' ,CL1 'R' ,CL1 'E' ) ) 

The following MSGEDIT macro, coded in an inbuffer or outbuffer subgroup, 
causes the characters occupying the tenth through twentieth bytes of each buffer 
to be deleted, and the remaining data to be shifted left to fill the gap caused by 
deletion. 

EDIT10 MSGEDIT ( (R, ,9,20 ) ) 



The following MSGEDIT macro, coded in an inheader or outheader subgroup, 
causes the character occupying the byte to which the scan pointer is currently 
pointing to be removed; subsequent data in the segment is shifted one byte left to 
fill the gap. Note the defaults. 



i 
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I 



EDIT1 1 MSGEDIT ( ( R, , , SCAN ) ) 

The following MSGEDIT macro, coded in an outbuffer subgroup, causes three 
EBCDIC SYN control symbols (X'32') to be inserted in each segment, beginning 
at the thirty-first byte. 

EDIT12 MSGEDIT ( ( I , ( X ' 32 ' , 3 ) , 3 1 ) ) 

The following MSGEDIT macro, coded in an inblock, inbuffer, or outbuffer 
subgroup, causes the EBCDIC blank character (X'40') to be replaced by 13 
EBCDIC idle characters (Xn?') wherever a blank occurs (BLANK=NO must be 
specified for this operation). In addition, the character string DOLLARS is 
replaced with the character $ wherever it appears, and two blanks are inserted 
after each period in the message. 

EDIT1 3 MSGEDIT ( ( RA, ( XL1 ' 1 7 ' , 1 3 ) , CLl ' '), * 

(RA,CL1 ' ; '$' , CL7 ' DOLLARS ' ), * 
( I , CL2 ' ' , CL1 ' . • ) ) , BLANK=NO 

When multiple operations are performed by a single MSGEDIT macro, the data 
inserted by insert operations is not considered when remove operations are 
performed. The macro should be in an inblock subgroup if the character string 
^DOLLARS' can extend across buffer boundaries. Thus in the above example, the 
two blanks inserted after each period would not be replaced by 1 3 idle characters 
each. 
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MSGFORM 



The MSGFORM macro 

• puts line-control characters into outgoing messages; 

• removes line-control characters (on a count basis) from incoming messages; 

• permits specification and overriding of blocking factors for outgoing messages; 

• permits variable-length reblocking of records for outgoing messages; 

• indicates whether an outgoing message is to be transmitted in transparent or 
non-transparent mode; 

• may be specified in the inblock and outheader subgroups. 

The MSGFORM macro is optional; it may be included in inblock and outheader 
subgroups only. When coded in an inblock subgroup, MSGFORM must appear 
before any other macro that might cause data movement. The MSGFORM macro 
should be coded in the outheader subgroup of a Message Handler assigned to a 
Hne group, and should not be in the outheader subgroup of the MH for an appli- 
cation program. The MSGFORM macro permits the user to divide his outgoing 
messages into logical blocks of data based on a maximum size or a maximum 
number of subblocks per block. The user specifies blocking factors in the oper- 
ands of the TERMINAL or MSGFORM macro; the blocking factors specified in 
MSGFORM override those specified in TERMINAL. In addition, the blocking 
factor may be defined as a number of variable-length subblocks. If MSGFORM 
specifies blocking factors, TCAM inserts appropriate blocking control characters 
into outgoing messages at the beginning and end of each message and at the 
locations indicated by the TERMINAL or MSGFORM operands. If blocking 
factors are not specified in either the MSGFORM or the TERMINAL macro, the 
EOT line-control character is the only one inserted in messages for start/stop 
terminals, and no line-control characters are inserted in messages to BSC termi- 
nals. No buffer space need be reserved for the characters inserted by 
MSGFORM. MSGFORM inserts EOA, ETX, and EOT characters where needed. 
These and the blocking characters are not inserted at the time MSGFORM is 
executed; rather, the characters are inserted after all executable macros in the 
outgoing group have been executed. When the blocking factor is at a maximum 
number of subblocks per block, the subblock delimiters must be in the data before 
MSGFORM executes. For IBM 2260 (Remote), IBM 2265, and BSC stations, 
STX characters are also inserted. For more information on the line-control 
scheme utilized by TCAM, see Defining Terminal and Line Control Areas . 



MSGFORM has the following format: 



Name 


Operation 


Operands 


[symbol] 


MSGFORM 


[BLOCK=integer] [,SUBBLCK=integer] 

[,COUNT=integer] [,SENDTRP= ( YES, PAD )] 

<YES,NOPAD> 
(NO ) 

[,ENDCHAR=subblock delimiter] 
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symbol 



BLOCK=mteger 



SUBBLCK=integer 



sendtrp= ( yes, pad 

] yes, nopad 
(no 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the number of bytes in each subblock of data for incoming 
and in each block of data for outgoing messages in transparent or non-transparent 
mode. 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' or 
XLn' ' characters must be specified. 
Maximum: 65535 or a hexadecimal field of two bytes. 

Notes: If this operand is not specified for output, the value used is that specified 
by the blocksize suboperand of the NTBLKSZ= operand of the TERMINAL 
macro, or by the TBLKSZ= operand of the TERMINAL macro for the destina- 
tion station. 

When data is to be sent in transparent mode, the number of buffers assigned for 
BUFOUT must be large enough to contain an ETB block. The value is specified 
in the BLOCK= operand of the MSGFORM macro or the TBLKSZ= operand of 
the TERMINAL macro. 

When both the BLOCK= and the ENDCHAR= operands are coded in the 
inblock subgroup of an MH assigned to a Une group, the other operands of the 
MSGFORM macro cannot be coded. 

On input, TCAM inserts an EOB or an ETB line-control character after each 
number of bytes specified by integer . 



Function: Specifies the number of bytes per ITB character for outgoing messages 

in non-transparent mode to BSC stations. 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' or 

XLT ' characters must be specified. 

Maximum: 255 or a one-byte hexadecimal field. 

Notes: If this operand is not specified, the value used is that specified by the 

subblocksize suboperand of the NTBLKSZ= operand of the TERMINAL macro 

for the destination station. 

TCAM inserts an ITB control character after each number of bytes specified by 
integer . 



Function: Specifies whether this message is to be sent out in transparent mode. 
Default: NO 
Format: YES 

YES, PAD 

YES, NOPAD 

NO 
Notes: YES should not be coded unless the message is being sent to a BSC 
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ENDCHAR=subblock delimiter 



COUNT=mteger 



Station. PAD is a default of YES and indicates that padding with blanks will be 
done to short blocks of data. SENDTRP can be coded YES or YES, PAD. YES, 
NOP AD specifies that no padding is to be done in transparent mode. NO speci- 
fies that the message is sent out in non-transparent mode. Padding or no padding 
applies only to the last block of the message. 



Function: Specifies the characters that terminate a subblock for outgoing mes- 
sages. Specifies the characters to be deleted from incoming messages. 
Default: None. Specification optional. 

Format: Character or hexadecimal. XLn' ' or CLn' ' must be coded as framing 
characters. 
Maximum: 8 bytes. 

Notes: Subblock delimiters, when required, must be in the output data before 
blocking is performed. 

When the ENDCHAR= and the BLOCK= operands are both coded in the 
inblock subgroup of an MH assigned to a Hne group, the other operands of the 
MSGFORM macro cannot be coded. 

When both the ENDCHAR= and the COUNT= operands are coded in the 
outheader subgroup of an MH assigned to a line group, the other operands of the 
MSGFORM macro cannot be coded. 

Since MSGFORM is coded in the outheader subgroup, but is the last macro to 
execute in the outgoing group, the user should code the ENDCHAR string in line 
code. 



Function: Specifies the maximum number of subblock delimiters in the variable- 
length blocks of data to be constructed for output operations. 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing X' ' 
characters must be specified. 
Maximum: 255 or a one-byte hexadecimal field. 

Notes: When both the ENDCHAR= and the COUNT= operands are coded in 
the outheader subgroup of an MH assigned to a line group, the other operands of 
the MSGFORM macro cannot be coded. 
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symbol 



mask 



MSGGEN 



The MSGGEN macro 

• generates an unqueued message; 

• is optional in inmessage and outmessage subgroups; 

• may be issued more than once in a subgroup. 

MSGGEN generates a message if the errors specified by the error mask operand 
match the bits set in the message error record (see Appendix B for a description 
of the message error record). If a zero mask is specified, the message is generated 
unconditionally. The generated message bypasses all normal functions, such as 
MH processing, queuing, logging, and buffer requesting. The MSGGEN macro 
informs the user of an error more rapidly than does the ERRORMSG macro, but 
does not return the header of the message in error, as the latter macro does. 

If MSGGEN is specified in an inmessage subgroup, the generated message, as 
specified by an operand, is sent to the originating station; if specified in an 
outmessage subgroup, the message is sent to the destination station. MSGGEN 
may be specified more than once within a subgroup. 

This macro may be used to generate a message based on an error condition 
detected in a logical message formed by deblocking an incoming physical message. 
Its use requires that the inblock subgroup's SETEOM macro specify 
PROCESS=YES. Logical messages are discussed in Handling Logical Messages 
in this chapter. 



Name 


Operation 


Operands 


[symbol] 


MSGGEN 


[mask], (message ) 
1 fieldnamer 

[,CONNECT=)AND\] 

toR ] 
[,CODE=(tablename H 

Ino f 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (see the description of the message error record in 
Appendix B ). 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X' ' is used, leading zeros must be coded. If XL5' ' is 
used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 
Notes: Omitting the operand or an all-zero mask causes unconditional execution. 
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i message ) 
fieldnames 



Function: Specifies the message or the location of the message to be sent to the 

originating or destination station, depending on whether MSGGEN is issued in an 

inmessage or outmessage subgroup, respectively. 

Default: None. This operand must be specified. 

Format: message or fieldname, message is the actual message to be sent, and has 

a maximum length of 24 bytes. It must be framed, either by C \ CLn' ', X' ', or 

XLn' ' framing characters, fieldname is the symbolic name of the field containing 

the message. It must not be specified with framing characters. 

Notes: The message may be specified in EBCDIC and translated as specified by 

the CODE= operand, or it may be specified in line code if no translation is to 

occur. 

The field referred to by fieldname must have as its first byte the hexadecimal 
count equal to the number of bytes in the rest of the field. The maximum number 
of bytes in the message portion of the field is 24. 

All line-control characters, including the EOT, must be coded by the user in his 
message, with the following exceptions: 

• TCAM provides the EOA line-control characters for the IBM 1030, IBM 1050, 
IBM 1060, IBM 2740, 1 15A and 83B3 stations. 

• TCAM provides an EOT character for BSC stations. 

• The user should not insert block-checking characters (EOB) in MSGGEN 
messages directed to a start-stop station. 

If the user inadvertently inserts block-checking characters (for instance, EOB) in 
MSGGEN messages directed to a start-stop station, no checking occurs. For BSC 
stations, the presence of block-checking characters will cause checks to be made. 
Messages sent out by MSGGEN are never transmitted in transparent mode. 



connect=Jand 1 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. OR specifies that the 

macro is to be executed if any bit specified by mask is on in the message error 

record. 



CODE=Jtablename| 



Function: Specifies the type of translation for the generated message. 

Default: None. Specification optional. 

Format: tablename or NO. 

Notes: tablename is specified as described for the TRANS = operand of the line 

group DCB macro. Register notation may not be used. The user may devise and 

specify his own translation table as described for the CODE macro. 

NO specifies that the message is not to be translated. If this operand is omitted, 
the message is translated using the translation table specified in the hne group 



i 
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DCB for the line. If this operand is omitted and no translation table is specified in 
the line group DCB macro, no translation occurs. 

A message generated by MSGGEN may not be directed to a distribution list or to 
an application program when specified in an inmessage subgroup. 

Note: A premature disconnection on a switched line will prevent the message 
from being returned to the originating station; the message will be lost. 
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MSGLIMIT 



The MSGLIMIT macro 

• limits the number of messages to or from a station during a single transmission 
sequence; 

• is effective only when used with a nonswitched line; 

• is ineffective for buffered stations; 

• is optional in the inblock, inheader, and outheader subgroups of an MH. 

• is ineffective in the outheader subgroup if send priority is specified in the DCB 
macro. 

MSGLIMIT limits the number of messages that can be transmitted to or accepted 
from a single station on a nonswitched line following a positive response to 
invitation or selection. If coded in an inblock subgroup, MSGLIMIT limits 
physical transmission sequences initiated by a station. If coded in an inheader 
subgroup, MSGLIMIT limits the number of messages entered by a station or 
application program during a single transmission sequence; if coded in an out- 
header subgroup, MSGLIMIT limits the number of messages sent to a station or 
appUcation program during a single transmission sequence. For instance, for 
stations that are polled, MSGLIMIT in the inheader subgroup causes the current 
station to cease to be polled once the specified maximum number of messages is 
reached; the next entry is then polled. If no limit is set for polled stations, each 
station is polled until it has no more messages to enter (negative response). 

MSGLIMIT has no effect when used with a switched Une or with buffered stations 
on a nonswitched Une. The MSGLIMIT macro is optional in inheader and out- 
header subgroups. Its use is suggested for IBM 2260 and 2265 terminals; the 
outheader subgroup for these terminals should include a MSGLIMIT macro 
specifying a limit of one message in inquiry appUcations (in order to ensure that a 
response message is not erased before it can be read). For a description of the use 
of MSGLIMIT with a contention terminal, see Transmission Priority for Non- 
switched Contention Stations in the chapter Terminal and Line Control Area 
Definition . 

If a MSGTYPE macro or user code is used to cause MSGLIMIT to be executed 
only for certain types of messages, only those subsequent messages examined by 
the same MSGLIMIT macro will be counted when the limit for a station is being 
determined. If send priority is specified, the MSGLIMIT macro will have no 
effect. When the limit is reached the send priority condition will cause more 
output (if ready) to be sent to the terminal. The send priority will make the effect 
of the MSGLIMIT macro transparent to the user. 



Name 


Operation 


Operands 


[symbol] 


MSGLIMIT 


rinteger)^ 
1 opfieldj 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 
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{integer | 
opfield i i 

Function: Specifies the number of messages or the location of the number of ^ 

messages that the user wishes to transmit to or receive from each terminal on the 
line. 

Default: None. This operand must be specified. 

Format: integer or opfield. integer may be specified either in decimal or hexade- 
cimal format. If hexadecimal format is specified, framing X' ' or XLn' ' characters 
must be coded, opfield must be the same as the name of a one-byte option field 
defined by an OPTION macro. 

Maximum: For integer, 255 or a one-byte hexadecimal field. 
Notes: If integer is specified, all stations processed bylhis MH are limited to the 
same MSGLIMIT value. If opfield is specified, the option field contains the hmit 
of consecutive message transmissions that is allowed to or from a station. Use of 
this operand allows the message limit specification to be different for each station. 
If the option field cannot be found, MSGLIMIT does not execute, and a return 
code of X'04' is set in the low-order byte of register 15. 



( 
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symbol 



MSGTYPE 



The MSGTYPE macro 

• controls the path of a header through an MH; 

• is optional in inheader and outheader subgroups (and not permitted in any 
other subgroup); 

• may be used more than once in a subgroup. 

MSGTYPE enables the user to categorize incoming or outgoing messages into two 
or more message types, each of which he processes in a different manner. 

Use of MSGTYPE is optional. Any number of MSGTYPE macros may be issued 
within a subgroup, provided that they all examine the same position in the buffer 
for the message-type characters. Only one field in a header per inheader or 
outheader subgroup may contain message-type characters, and only one sequence 
of code beginning with a MSGTYPE macro is executed in an inheader or out- 
header subgroup for any one incoming or outgoing message. MSGTYPE may be 
used only within inheader and outheader subgroups. 

The use of MSGTYPE is discussed in the Variable Processing within a Message 
Handler section of this chapter. 

MSGTYPE has the following format: 



Name 



[symbol] 



Operation 



MSGTYPE 



Operands 



conchars 
' TABLE=name,EXIT=name 



[,BLANK=/YES 






NO 

f char 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



conchars 



Function: Specifies the character or character string to be compared with the 
message type field in the message header. 

Default: None. Specification optional. The conchars operand cannot be used 
when the TABLE = and EXIT= operands are used. 

Format: One to eight nonblank characters or hexadecimal format. If character 
format is used, the string may be unframed or framed with C* ' or CLn' ' charac- 
ters. If hexadecimal format is used, the string must be framed with X' ' or XLn' ' 
characters. 

Notes: When using the conchars operand, the next nonblank character or charac- 
ter string in the header buffer (after the current setting of the scan pointer) is 
compared with a character or character string specified by conchars . If the 
conchars field matches the field in the header buffer, all instructions between this 
MSGTYPE macro and the next MSGTYPE macro (or the next delimiter, if there 
is not another MSGTYPE macro) are executed. The next MSGTYPE macro is 
not executed, and a branch is made to the next subgroup. If the conchars field 
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TABLE=name 



EXIT=name 



BLANK= ( YES 
JNO 
(char 



does not match the field in the header buffer, the scan pointer is reset to its 
position before the comparison, and control passes to the next MSGTYPE macro 
in the current subgroup, or, if this is the last MSGTYPE macro in the subgroup, to 
the next MH subgroup. 

If the MSGTYPE macro has no operands, the group of instructions that immedi- 
ately follow this MSGTYPE macro will process the message header not processed 
by a preceding MSGTYPE macro with a conchars operand. A MSGTYPE macro 
with no operands may be used only at the last of a series of MSGTYPE macros 
with conchars operands. 

If MSGTYPE macros are used with and without operands, either some message- 
type field should always be specified, or care should be taken, if the field is 
omitted, that the next field cannot match any of the strings specified by the 
conchars or TABLE= operands in the series of MSGTYPE macros. 



Function: Provides the name of the first of a series of one or more TYPETABL 
macros. See the description of the TYPETABL macro. 

Default: None. Specification optional. The conchars operand cannot be used 
when the TABLE= and EXIT= operands are used. 
Format: Must conform to the rules for assembler language symbols. 
Notes: When using the TABLE = operand, the next nonblank character in a 
header buffer (after the current setting of the scan pointer) is compared with a 
table of message-type characters generated by one or more TYPETABL macros, 
and the address of the next subgroup is placed in register 2. If a match is found, 
the scan pointer is moved one position to the right, and a branch is taken to the 
address in the table for that message type. When user processing of the message is 
completed, the user can branch to the next subgroup (BR 2) or to another address 
within the current subgroup. If no match is found in the table, the scan pointer is 
not moved, and a branch is taken to the address specified by the EXIT= operand. 

Since one execution of a MSGTYPE macro (using the TxABLE= operand) exami= 
ines one character in the message-type field of a header buffer, multiple characters 
can be included in the message-type field, and multiple MSGTYPE macros can be 
issued to examine these characters. 



Function: Provides the address to which this MSGTYPE macro will branch if the 

message-type character in the header buffer does not match any entry in the table 

pointed to by the TABLE= operand of this MSGTYPE macro. 

Default: None. Specification required when the TABLE = operand is specified. 

Invalid when the conchars operand is specified. 

Format: Must conform to the rules for assembler language. 

Notes: name is the symbolic address to which this MSGTYPE macro will branch 

on an unequal comparison. 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be considered 
as part of the header string when encountered in it. If EBCDIC blanks are to be 
counted as part of the header string, this operand also specifies whether some 
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other hexadecimal character is to be ignored when encountered in the header 

string. 

Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 

either character or hexdecimal format. If character format is specified, it may be 

unframed or framed with C ' or CLT ' characters. If hexadecimal format is 

specified, it must be framed with X' ' or XLT ' characters. 

Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X*40') is to be ignored by this 

macro whenever it is encountered in the header character string being checked 

against the control character string specified by the conchars operand. For 

example, if BLANK=YES is coded and an eight-byte field in the header is being 

checked by this macro, a blank appearing in the fifth byte of the field will be 

ignored, and the sixth through ninth bytes will be considered to be the last four 

bytes of the field (assuming that no blanks are coded in the sixth through ninth 

bytes). 

NO specifies that the EBCDIC blank character is to be treated Uke any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparision and goes on to check the 
next character in the header. If BLANK = char is coded and char is not the 
EBCDIC blank character, the EBCDIC blank is not ignored by this macro when it 
is encountere4 in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, Uke any other character. 

Note: The use of char is invalid when using the TABLE= operand. 

Example: 

The beginning of an MH using MSGTYPE is shown in Figure 21. Type A mes- 
sages are processed and forwarded to terminal NYC, type B to terminal BIX, and 
all others to an application program. 



MHA STARTMH LC=OUT 



LC= must be coded 
for STARTMH 



INHDR 



Delimiter 



SEQUENCE 

ORIGIN 

DATETIME 

COUNTER 



MSGTYPE 



FIELD 



C'A' 



Macro instructions 
executed for all 
header segments 

Count incoming 
segment 

Test for Type A 
messages 



Macro instructions 
executed for all Type 
A messages 



FORWARD 



DEST=CL3*NYC' 
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MSGTYPE 



FORWARD 

MMSGTYPE 

FORWARD 



INMSG 
etc. 



C'B' Test for Type B 

messages 

Macro instructions 
executed for all Type 
B messages 

DEST=CL3'BIX' 

DEST=CL8 ' PROCESSQ ' Macro instruction 

executed for all other 
message types 

Delimiter 



Figure 21. Example of Using MSGTYPE Macro Instruction 

Additional examples: 

1. Message-type field of the header buffer is AC. 





MSGTYPE 


A 


MSGTYPE 


C 


user code 




BR 


NF 


user code 




BR 


MAIN 


TYPETABL 


ATYPE 


TYPETABL 



TABLE=MA1N , EXIT=NF 
TABLE=ATYPE , EXIT=NF 



A,ROUTINE=A 
C,ROUTINE=C 

2. Series of MSGTYPE macros using conchars operands followed by a 
MSGTYPE macro using TABLE= operand. 



MTA 



MTB 



MT1 



MSGTYPE C' ATYPE' 

user code 

MSGTYPE C'BYTYPE' 

user code 

MSGTYPE TABLE=TABLE1 ,EXIT=EXIT1 



If the header message has a message type of ATYPE or BTYPE, the user code 
following the MSGTYPE macro named MTA or MTB will be executed, and a 
branch will be taken to the next MH subgroup. If the message type is not 
ATYPE or BTYPE, the scan pointer is reset to its position before the compari- 
son, and the MSGTYPE macro named MTl will execute as shown in additional 
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example 1. 

3. MTA MSGTYPE C ' ATYPE ' 

user code 
MTB MSGTYPE 

user code 
MT1 MSGTYPE TABLE=TABLE1 ,EXIT=EXIT1 

If the message type is ATYPE, the MTA user code is executed, and a branch is 
taken to the next MH subgroup. If it is not ATYPE, the scan pointer is reset to 
its position before the comparison, the MTB user code is executed, and a 
branch is taken to the next MH subgroup. 

To get to MTl, the user would have to branch there from either the MTA user 
code or the MTB user code. If a branch to MTl is taken from MTA, the scan 
pointer will be situated at the last position of the message-type field. If a 
branch to MTl is taken from MTB, the scan pointer will be situated at its 
position before the comparison. 



i 
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ORIGIN 



The ORIGIN macro 

• checks the vaUdity of the origin field in a message header; 

• sets a bit in the message error record for the message if the origin field is 
invalid; 

• permits identification of a switched station calling the computer; 

• is optional in the inheader subgroup and is not permitted in any other subgroup. 

The function of the ORIGIN macro depends upon the kind of connection made 
with the station. For nonswitched stations, ORIGIN verifies that the origin field 
in the header contains the symboUc name of the station that was invited to send 
the message (that is, the origin field is compared with the name of the terminal 
table entry for the station that was contacted). If the names are not the same, an 
error flag is set in bit 1 of the message error record for the message. 

For switched stations, ORIGIN both checks the vahdity of the origin field in the 
header and identifies the caUing station to TCAM. Unless the calling station is a 
BSC station that transmits a unique ID sequence upon successfully calling the 
computer, TCAM does not know what station is on the line until an ORIGIN 
macro is issued in the MH. Once an ORIGIN macro is issued, TCAM compares 
the name in the origin field of the message header with the terminal table entries 
for the stations assigned to Unes in the Une group to which the line connecting the 
calling station to the computer is assigned. If a match is found, TCAM assumes 
that the station named in the origin field is the calling station. If no match is 
found, an error flag is set in bit 1 of the message error record for the message. 

Inheader subgroups for switched lines to stations that do not have unique ID 
sequences and that may call the computer and enter messages should include an 
ORIGIN macro, as this is the only means TCAM has of identifying the calling 
station in this situation. 

An inheader subgroup that handles messages entered only by BSC stations having 
unique ID sequence requires no ORIGIN macro. When an ORIGIN macro is 
included in the inheader subgroup that processes header segments entered by such 
a station, the name in the origin field, if valid, takes precedence over the name 
associated with the ID sequence in the invitation Ust; that is, TCAM assumes that 
the station named in the origin field is the station that entered the message. 

For switched stations assigned to a Une for which a TERMINAL macro coded 
UTERM= YES has been issued, the position of ORIGIN in the inheader sub- 
groups determines whether the option fields assigned to the line or those assigned 
to the station will be updated by MH macros when a station calls the computer. 
Inheader macros executed before ORIGIN refer to option fields assigned to the 
line by a TERMINAL macro coded for the line, while macros executed after 
ORIGIN refer to option fields assigned to the station by a TERMINAL macro 
coded for that station. (For a more detailed discussion of the relationship be- 
tween the ORIGIN macro and the TERMINAL macro coded for a line, see 

Coding the Terminal Macro for a Line in Defining Terminal and Line 

Control Areas .) 

If ORIGIN is used with a message having a multiple-buffer header and entered 
from a station on a switched Une, ORIGIN must be executed for the first header 
buffer in order to effectively identify the station. 



( 
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A CODE macro must be issued before ORIGIN (unless the line code is 
EBCDIC). 

Care must be taken in entering a character string in an origin field in the message 
header to ensure that it matches a terminal table entry. A character string entered 
in lowercase characters from an IBM 2770 station, for example, will not match a 
terminal table entry name that is in uppercase characters. See additional use for 
the ORIGIN macro in Appendix J, Concentrating and Deconcentrating Messages . 



The ORIGIN macro has the following format: 



Name 


Operation 


Operands 


[symbol] 


ORIGIN 


["integer"! 
LXTF' . 



symbol 



[integer] 
X'FF J 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbol (see the symbol 

entry in the Glossary ). 



Function: Specifies the number of characters in the origin field of a message 

header. 

Default: XTF' 

Format: Decimal or hexadecimal. If hexadecimal format is specified, framing X' ' 

or XLT ' characters must be used. 

Maximum: 8 

Notes: If integer is specified, that many characters are considered to be the origin 

field. Embedded blanks are ignored. 

XTF' indicates that the origin field is of variable length. The origin field is 
considered to end at the next blank. 

Note: // an ORIGIN macro determines that the source of a message on a 
nonswitched line is invalid, a return code of XV4' is set. 
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PATH 



The PATH macro 

• alters a path-switch byte, thereby permitting dynamic variation of the path of a 
message through an MH; 

• is optional in inblock, inheader, inbuffer, outheader, and outbuffer subgroups 
(and not permitted in any other subgroup). 

One-byte option fields are used to maintain switches known as path switches . 
These switches are located in option fields defined by OPTION macros. The 
switches must be set initially by the OPDATA= operand of the TERMINAL or 
TPROCESS macro (if the option fields are not initiaUzed, the PATH macro 
provides a return code of X'OO'). The setting of path switches is examined by 
each delimiter macro as the message reaches the subgroup it controls (the user 
specifies by the PATH operand of each delimiter which path-switch bits are to be 
examined). More than one option field may be specified for each station; each 
path-switch byte so defined consists of eight binary switches. 

If any of the binary switches tested by a delimiter is on, the subgroup controlled 
by that delimiter is executed; if none of the binary switches tested is on, control 
passes to the next delimiter. 

The user may specify a character string (consisting of one to eight nonblank 
characters). If this character string appears in the header of a message, the PATH 
macro with that character string sets one or more specified path switches. If no 
character string is specified, the switches are set unconditionally. 

PATH may specify any number between zero and 255, inclusive. The switches 
remain set until reset by a PATH macro specifying the same option field, until 
modified by user code and LOCOPT, or until modified by a DATOPFLD opera- 
tor command. 



The use of PATH is discussed in the Variable Processing within a Message 
Handler section of this chapter. 



Name 


Operation 


Operands 


[symbol] 


PATH 


switch,opfield [, conchars[, BLANK= (yES)]] 

^NO> 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



switch 



Function: Specifies the path switch setting to be made for the byte residing in the 

option field named by the op field operand. 

Default: None. This operand must be specified. 

Format: Decimal or hexadecimal. If hexadecimal format is specified, framing X' 
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opfield 



conchars 



or XLV ' characters must be used. 
Maximum: 255 or a one-byte hexadecimal field. 

Notes: If is specified, all eight path switches are turned off. If 255 (or XTF') is 
specified, all switches are turned on. 



Function: Specifies the path-switch byte to be operated upon. 

Default: None. This operand must be specified. 

Format: The name of a one-byte field in the option table as defined by an 

OPTION macro. 

Notes: If the option field cannot be found, the path-switch byte is not operated 

upon, and a return code of X'OO' is set in the low-order byte of register 15. 

If PATH is coded in the incoming group of an MH for a line group, the specified 
option field for the station entering the message is operated upon. If PATH is 
coded in the outgoing group of a hne MH, the specified option field for the 
destination station is operated upon. If PATH is coded in the outgoing group of 
an MH assigned to an application program, the option field associated with the 
process queue to which the GET macro is directed is operated upon. If the macro 
is coded in the incoming group of an MH assigned to an application program, the 
option field for the process entry associated with the DCB named in the PUT 
macro is operated upon. 



Function: Specifies the character or character string that, if found in the header as 

the next nonblank field, causes execution of the function. 

Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 

character format is used, the string may be unframed or framed with O ' or CLn* ' 

characters. If hexadecimal format is used, the string must be framed with X' ' or 

XLn' ' characters. 

Notes: This operand should be coded only in PATH macro issued in an inheader 

or outheader subgroup. 

If this operand is omitted, the PATH function is performed unconditionally. If the 
next field in the header does not match this operand, the function is not per- 
formed. 



BLANK= (char 

/yes 



1^ 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES or NO or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLl* ' characters. If hexadecimal format is 
specified, it must be framed with X* ' or XLT ' characters. 

Notes: This operand is meaningless unless the conchars operand is also specified. 
YES specifies that the EBCDIC blank character (X*40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
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against the control character string specified by the conchars operand. For 
example, if BLANK=YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be ^ 

ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, Hke any other character. 

Example: 

Figure 22 shows the outline of an inmessage group of an MH. Messages with A, 
B, or C in an appropriate field are routed through the incoming group by PATH 
macro instructions. The switch settings enable the user to select appropriate 
inbuffer and inmessage subgroups. Message type A passes through the first 
inbuffer subgroup and the second inmessage subgroup, etc. 

Note: In the case of multiple -buffer headers, the entire control-character /^' 

field must appear in the first header segment. '^ 



i 
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Name 


Operation 


Operands 


Comment 


VARYPATH 


STARTMH 


LC=OUT 


Inheader subgroup executed 




INHDR 

• 




for all messages. 




• 
• 
PATH 


4, SWITCH, C A' 


Sets switch for type A 
messages ( not executed for 




• 




others. ) 





• 
PATH 


2, SWITCH, C'B' 


Sets switch for type B 
messages. 




PATH 

• 


1 ,SWITCH,C'C' 


Sets switch for type C 
messages. 




INBUF 




4, SWITCH 


This inbuffer subgroup is 
executed if switch is 4. 




• 
INBUF 


PATH-( SWITCH, 4 ) 


This inbuffer subgroup is 
executed if switch is 2. 




INBUF 


PATH=( SWITCH, 2 ) 


This inbuffer subgroup is 
executed if switch is 1 . 




INMSG 


PATH=( SWITCH, 3 ) 


This inmessage subgroup is 
executed if switch is 1 or 2 . 




INMSG 


PATH=( SWITCH, 4) 


This inmessage subgroup is 
executed if switch is 4. 




INEND 







Figure 22. Example of Using the PATH Macro Instruction to Vary MH Processing 
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PRIORITY 



The PRIORITY macro 

• specifies priority handling for messages; 

• is optional in an inheader subgroup of the MH; 

• may be used more than once in the subgroup. 

PRIORITY provides handling of outgoing messages according to priority levels. 
The priority level may be entered in the message header by the user, or it may be 
specified by an operand of the PRIORITY macro. The permissible priority levels 
for each station or application program are specified in the TERMINAL or 
TPROCESS macro for that destination. If queuing by Une rather than queuing by 
terminal is specified, the first TERMINAL macro for the line contains the permis- 
sible priority levels for all stations on the line. If subsequent TERMINAL macros 
for the same line specify priority levels, they are ignored. If a message priority is 
requested that is not permitted, the message is assumed to have the next lower 
permissible priority. The PRIORITY macro must be specified within the subgroup 
in the same relative order as the header field on which it acts. 

Absence of the PRIORITY macro causes a priority level of zero to be assigned to 
the messages. 

For more information on message priority, see Message Priority and Queuing in 
Defining Terminal and Line Control Areas. 

TCAM converts the decimal priority levels specified by the LEVEL= operand of 
the TERMINAL or TPROCESS macro to their one-byte hexadecimal equivalents. 
If the priority is specified in a message header, it may occupy a one-byte field and 
should provide the hexadecimal equivalent of a decimal priority level specified by 
the LEVEL= operand of the TERMINAL or TPROCESS macro. For example, if 
PRIORITY is executed after a CODE macro (that is, the message segment has 
been translated from line code to EBCDIC), and if messages entered by a particu- 
lar station may be assigned priorities of 1, 2, A, B, or C on output, the LEVEL= 
operand of the TERMINAL macro for that station should be coded 
LEVEL=(193, 194, 195, 241, 242). Here, 193 is the decimal representation of 
the hexadecimal equivalent of the EBCDIC character A; 241 is the decimal 
representation of the hexadecimal equivalent of the EBCDIC character 1, etc. In 
this case, a message with a line-code character 1 assigned as its priority would be 
higher in priority than a message assigned a line-code character A, B, or C. 

On the other hand, if PRIORITY is executed before a CODE macro, and if the 
messages are being entered by a 1050 station and may be sent with priorities of 1, 
2, A, B, or C, the LEVEL= operand of the TERMINAL macro should be coded 
LEVEL=(2, 4, 226, 228, 231); here 2 is the decimal representation of the 
hexadecimal equivalent of the 1050 line-code character 1; 226 is the decimal 
representation of the hexadecimal equivalent of the 1050 line-code character A, 
etc. In this case, a message with a line-code character A assigned as its priority 
would be higher in priority than a message assigned a Une-code character 1 or 2. 



M 
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Name 


Operation 


Operands 


[symbol] 


PRIORITY 


[integer] [ ,conchars[ , BLANK = 


Uhar; 


]] 



symbol 



integer 



conchars 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



Function: Specifies the priority level to be assigned to this message. 
Default: None. Specification optional. 
Format: Unframed decimal integer. 
Maximum: 255 

Notes: If this operand is omitted, TCAM assumes that the priority level is con- 
tained in the next nonblank byte following the current setting of the scan pointer. 
If the priority level is not one that the TERMINAL or TPROCESS macro speci- 
fies as permissible, the next lower permissible priority is assumed. 



Function: Specifies the character or character string that, if included in the 

message header, causes execution of the PRIORITY macro specifying that string. 

Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 

character format is used, the string may be unframed or framed with C ' or CLn' ' 

characters. If hexadecimal format is used, the string must be framed with X' ' or 

XLn* ' characters. 

Notes: If this operand is omitted, PRIORITY is specified unconditionally. If the 

control characters do not match, the PRIORITY macro does not execute and 

control passes to the next instruction. 

If this operand is specified, but the integer operand is omitted: 

• The message priority is assumed to be contained in the message header as the 
next nonblank character following control characters. 

• A comma must precede the conchars operand. 



BLANK=(YES 
f char 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLl' ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 
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Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK= YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenver it is encountered in the header string being compared to the string 
specified by the conchars operand. That is, the macro automatically skips over 
the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it i$ 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, Hke any other character. 

If the integer and conchars operands are omitted, the priority is assumed to be in 
the message header, in the next nonblank character following the current setting 
of the scan pointer. 

In the case of multiple-buffer headers, the priority, if desired, must be determined 
for the first header segment to pass through the inheader subgroup. This can be 
ensured in one of two ways: 

1 . The priority field in the header, if used, must be in the first header segment 
(and for messages from buffered terminals, in the first hardware buffer if the 
hardware buffer is smaller than the MCP buffers), or 

2. The integer operand must be specified to provide the priority, and any control 
characters used to execute the PRIORITY macro must be in the first buffer 
(and for messages from buffered terminals, in the first hardware buffer, if the 
hardware buffer is smaller than the MCP buffers). 

Example: 

The following examples show the various ways message priority may be specified. 
It is assumed that the LEVEL = operand of the TERMINAL macro for the 
destination station is coded LEVEL=(241, 243, 245, 247). 






i 
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PRIORITY Macro 


Header Fields 


Priority given message 




in EBCDIC 


(decimal notation) 


PRIORITY 


5 


5 


PRIORITY 


6 


5 


PRIORITY 241 


3 


5 


PRIORITY 241 , PRI 


PRI 


241 


PRIORITY ,PRI 


PRI3 


243 


PRIORITY ,PRI 


PRO 


Priority of isassigned 
( the macro is not executed) 



Figure 23. Example of Using the PRIORITY Macro Instruction 
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REDIRECT 



The REDIRECT macro 

• queues a message for an additional destination; 

• is optional in an inmessage or outmessage subgroup of an MH; 

• may be specified more than once within a subgroup. 

REDIRECT queues a message for a destination in addition to the destinations 
specified by the FORWARD macro, when errors specified by the mask operand 
are detected. The bits specified by the error mask operand are compared with the 
setting of the bits in the message error record for the message. If specified bits in 
the message error record are on, the REDIRECT macro is executed; otherwise, 
the REDIRECT macro is not executed. 

The REDIRECT macro may not be used for redirecting messages being transmit- 
ted in initiate mode (see the INITIATE macro), or for redirecting error messages 
(see the ERRORMSG macro). 

The additional destination specified may be any single, group, process, or cascade 
list entry in the terminal table. A distribution list cannot be specified as the 
additional destination. 

REDIRECT may be used to route unsent messages to an application program, to 
return them to the originating station, or to send them to the alternate destination 
when the intended destination is inoperative. 



If REDIRECT is specified, it must appear in an inmessage or outmessage sub- 
group of an MH. 



Name 


Operation 


Operands 


[symbol] 


REDIRECT 


[mask][,CONNECT=/AND\ ] 
lOR / 

[,DEST=(destname]] 
<J opfield > 
\ ORIGIN ) 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



mask 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ters must be specified. If X* ' is used, leading zeros must be coded. If XL5' ' is 
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connect=(and) 
loR / 



used, leading zeros may be omitted. 

Maximum: 16777215 or a hexadecimal field of five bytes. 

Notes: Omitting the operand or an all-zero mask causes unconditional execution. 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: AND or OR. 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by mask are on in the message error record. 

OR specifies that the macro is to be executed if any bit specified by mask is on in 
the message error record. 



DEST=( destname 
' opfield 
* ORIGIN 



Function: Specifies the additional destination. 

Default: DEST=ORIGIN 

Format: destname, opfield, or ORIGIN, destname may be up to eight bytes in 

length and is the name of any single, group, or cascade Hst entry in the terminal 

table. It must be specified within framing C \ CLn* ', X' ' or XLn' ' characters. 

opfield is the unframed name of an option field defined by an OPTION macro, 

and cannot be named ORIGIN. 

Notes: If an invalid destination is specified, REDIRECT does not execute. 

opfield refers to an option field up to eight bytes, containing the name of the 
destination. The additional destination is the station 

• specified in the option field assigned to the originating station or application 
program, if 1) REDIRECT is used in an inmessage subgroup and 2) if the 
originating station is not a switched station that called the computer to enter 
the message but did not identify itself by means of a unique ID sequence or by 
a vaUd origin field checked by an ORIGIN macro; 

• specified in the option field assigned to this line by a TERMINAL macro coded 
for a line if the originating station is a switched station that called the computer 
to enter this message, but did not uniquely identify itself; 

• specified in the option field assigned to the destination station or appUcation 
program if REDIRECT is used in an outmessage subgroup. 

ORIGIN specifies that the message in error is to be sent to the station from which 
it originated (in addition to the destinations specified in the message header). 

If this operand is omitted or if DEST= ORIGIN is specified, and the originating 
station is a switched station that has called the computer to enter the message, the 
station must identify itself by a unique ID sequence or by a vaUd origin field as 
checked by an ORIGIN macro. Otherwise TCAM is unable to identify the station 
of origin and cannot route the message to it. 
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RETRY 



The RETRY macro 

• tries again to initiate contact with a switched station; 

• is optional in the inmessage subgroup. 



Name 


Operation 


Operand 


[symbol] 


RETRY 


INTVL=: integer 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



INTVL»integer 



Function: Specifies the number of seconds following which the computer is to try 

again to initiate contact with a switched station. 

Default: None. Specification required. 

Format: Unframed decimal integer greater than zero. 

Maximum: 65535 



If the RETRY macro is specified, the RETRY= operand of the TERMINAL 
macro also must be specified. The TERMINAL macro also must specify the 
DIALNO= operand and either the CLOCK= or the CINTVL= operand. 

For more information, see the RETRY= operand of the TERMINAL macro. 



( 
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SCREEN 



The SCREEN macro 

• modifies the Write operation for terminals with display screens; 

• is optional in outheader subgroups of Message Handlers for terminals with 
display screens. 

SCREEN may be used in an outheader subgroup of an MH to specify the type of 
modification to be made to the Write operation for the 2260, the 2265, or 3270. 
(See 3270 Information Display System in Appendix G for information on the 
SCREEN macro, special for the 3270.) If the user specifies the Write Display 
Control (WDC) operation, write operations begin at the position of the display 
cursor. Alternatively, the user may specify the Write Erase (WRE) function so 
that the screen is erased before the next segment is displayed, and writing begins 
at the top of the screen. Or, the user may specify the Une on which he wishes to 
write, using the Write at Line Address (WLA) function. 

If the WLA function is used, the user must specify the line address character 
desired as the first character of the header of the message to be written. If 
line-control is left in the message, the line-address character should follow any 
initial line-control characters. The user may insert the line address in the message 
header either by: 

• including the necessary assembler language instructions in an MH or in an 
application program. 

• using the MSGEDIT macro. 

The table below gives the appropriate line addresses in EBCDIC for 2260 termi- 
nals. The following MSGEDIT macro, executed in an outheader subgroup on the 
first segment of a message, would place the line address for Une number ten in the 
first byte of the header (assuming that the header contains no Une control): 

LINEADDR MSGEDIT ( ( I , XL1 ' F9 ' , ) ) 

The type of operation (WRE, WLA, WDC, XRE, XL A, XDC) to be performed 
for a display terminal is specified initially by the user in the TERMINAL macro 
for that terminal. (See the description of the ADDR= operand of the 
TERMINAL macros.) When the TERMINAL macro is executed, TCAM sets a 
byte in the terminal table entry to indicate the type of Write operation to be 
performed for aU messages directed to this terminal. The SCREEN macro 
changes the type of operation to be performed by modifying this byte (for exam- 
ple, from WLA to WRE). However, for remote operations, the change specified 
by SCREEN does not take effect until the next message is sent to the terminal; if 
WLA was changed by SCREEN to WDC, aU messages sent to the terminal after 
the current message would have a WDC operation performed for them, but the 
current message (that is, the message being processed when SCREEN executes) 
would have a WLA operation performed for it. For local operations, the change 
specified by SCREEN takes effect for the current operation. See device depend- 
ent considerations for 2260 and MH return codes. 

When WLA is changed to another Write operation by SCREEN, the user must 
still place the line address in the header of the current message, since a WLA 
operation will be performed for this message. If the operation- type operand of 
SCREEN is omitted, when SCREEN finishes executing, a return code is placed in 
register 15 to indicate what the setting of the terminal table byte was before 
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SCREEN changed it. User code may test the return code; if the code indicates 
that a WLA operation was being performed, a MSGEDIT macro may be executed 
to insert the Hne address. Otherwise, the user code may branch around the 
MSGEDIT macro (see the example following the macro description). 



Line Address Characters for the IBM 2260 Terminal 



Hexadecimal representation 


Selected line 


of EBCDIC line address 




FO 


1 


Fl 


2 


F2 


3 


F3 


4 


F4 


5 


F5 


6 


F6 


7 


F7 


8 


F8 


9 


F9 


10 


FA 


11 


FB 


12 



SCREEN has the following format: 



Name 



[symbol] 



Operation 



SCREEN 



Operands 



WRE 

iwLAi 

'WDC' 

\XRE 

fxLA 

,XDC 



[,conchars[,BLANK= ( YES 
NO 
char 



] ] 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 




Function: Specifies the type of write operation for the IBM 2265 (Remote) or the 

IBM 2260 (Local or Remote). 

Default: None. Specification optional. 

Format: WRE, WLA, WDC, XRE, XLA, or XDC. 

Notes: WRE specifies a Write Erase operation, the erasure of the screen before the 

next segment is displayed. 



( 
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conchars 



WLA specifies a Write at Line Address operation. The user must insert a line 
address character as the first character (following any initial Une-control charac- 
ters, if line control was left in the message) of the message to be written out. 

WDC specifies a Write Display Control operation. 

XRE specifies Write Erase with keyboard lock. 

XLA specifies Write at Line Address with keyboard lock. 

XDC specifies Write Display Control with keyboard lock. The keyboard lock 
feature causes the keyboard to be locked after the write. It can be used to force 
the terminal operator to look at the screen; perhaps for the purpose of reading and 
correcting a previously entered message that contained a syntax error. XLA, 
XRE, and XDC can only be used if the 2260 or 2265 device is equipped with the 
keyboard lock feature. 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn* ' 
characters. If hexadecimal format is used, the string must be framed with X' ' or 
XLn' ' characters. 

Notes: If this operand is omitted, the SCREEN function is performed uncondi- 
tionally. If the next field in the header does not match this operand, the function 
is not performed. 

A SCREEN macro specifying no WRE, WLA, or WDC operation may be issued 
to check the type of write operation in effect for the message being processed 
without changing the operation type. See the example below. 

If WLA is changed to another Write operation, the user code in the outheader 
subgroup needs to know whether to cause a line-address character to be inserted 
in the current message. The following codes may be returned by SCREEN in 
register 15: 



Code 


Operation 


X'AO' 


WDC 


X'BO' 


WLA 


X'EO' 


WRE 



BLANK= 



char 
NO 
YES 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
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unframed or framed with C* ' or CLT ' characters. If hexadecimal format is 

specified, it must be framed with X' ' or XLT ' characters. 

Notes: This operand is meaningless unless the conchars operand is also specified. (, 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK= YES is coded and an eight-byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char is coded and char is not the EBCDIC 
blank character, the EBCDIC blank is not ignored by this macro when it is 
encountered in the header string, but is compared to the character in the corre- 
sponding space in the conchars string, like any other character. 

Example: 

The following code (in Figure 24) might be issued in an outheader subgroup to ^ 

determine whether the Write at Line Address (WLA) operation is specified in the H 

appropriate byte in the terminal table entry for the destination station for the 
message being processed, and to cause a line address of 10 to be placed in the first 
byte of the message header of the current message if WLA is specified in the 
terminal table entry. SCREEN is executed only for type A messages (as deter- 
mined by a field in the message header and the conchars operand of SCREEN). 



OUTHDR 








SCREEN 




/A 




LA 




5,X'B0' 




CLR 




5,15 




BNE 




CONTINUE 




MSGEDIT 




( (I,XL1 'F9' 


,0)) 


CONTINUE EQU 




* 




next 








instruct 


ion 







Figure 24. Example of Inserting Line Address 
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SEQUENCE 



The SEQUENCE macro 

• checks the input sequence number of an incoming message; 

• inserts the output sequence number in an outgoing message; 

• is optional in inheader and outheader subgroups on non-audio lines (and may 
not be used in any other subgroup); 

• should be specified only once in each subgroup. 

If specified in an inheader subgroup, SEQUENCE scans the input sequence 
number field in the header of each message. If the sequence number is not one 
greater than the sequence number of the last message received from the same 
station or appHcation program, an error flag is set in bit 3 or 4 of the message 
error record assigned to the message (depending on whether the number is high or 
low, respectively), and a return code indicating an error is set in register 15. 

The header field for the input sequence number may contain up to four characters 
of sequence (leading zeros may be omitted from the input sequence number 
entered at the station). This field should contain a decimal representation of the 
input sequence number, and should be delimited by a blank. For example, if the 
sequence number is twelve, the field should consist of a character 1 followed by a 
character 2 followed by a delimiting blank. At the time SEQUENCE looks at the 
field, the characters should have been translated into EBCDIC by a CODE macro. 
The user should reserve five bytes in his header (by the RESERVE= operand of 
the Une group DCB macro) for insertion of the output sequence number, if used. 

TCAM maintains internal counters in the terminal table entry to keep track of the 
incoming and outgoing sequence numbers for each station and application pro- 
gram. If the SEQUENCE macro is issued in an inheader subgroup, the first 
message from a station or application program must contain the same input 
sequence number as the input counter for that station or application program. 
TCAM initially sets each input counter to 1 . The next incoming message after 
9999 must be 1. Processing continues after the maximum number is reached. 

In general, SEQUENCE in an inheader subgroup causes the input counter to be 
incremented for each message having a correct input sequence number in the 
header. If, however, a CANCELMG macro causes a message to be canceled, or if 
a STARTMH macro causes retransmission of a message header segment, the input 
sequence number is not incremented. In the latter case, the number is increment- 
ed only when the segment is successfully retransmitted. 

If specified in an outheader subgroup, SEQUENCE places an output sequence 
number in the header of each outgoing message handled by the MH. The five- 
byte output sequence number (a blank followed by four EBCDIC characters) is 
inserted immediately following the byte to which the scan pointer is pointing when 
SEQUENCE executes. When the first message is sent to a station or application 
program, a 1 is placed in the output counter for that station or application pro- 
gram; as each succeeding output message is handled, this sequence number is 
incremented by 1 and the resulting number is inserted in the header. (A count is 
maintained for each station and for each terminal group where group addressing is 
used.) A message in error being routed using a REDIRECT macro retains the 
output sequence number placed in it. 
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symbol 



Use of SEQUENCE is optional. If used, it must appear within an inheader or 
outheader subgroup. Its position must correspond to the relative position, within 
the header, of the sequence-number field. 

TCAM increments the input sequence number counter in the terminal table entry 
only if a SEQUENCE macro is issued in the inheader subgroup. TCAM incre- 
ments the output sequence number counter in the terminal table entry automati- 
cally, each time that a message is sent to the station or appUcation program. 

If SEQUENCE is included in an inheader subgroup handling header segments 
entered by a switched station that calls the computer to enter the segments, and if 
the station does not have a unique ID sequence assigned to it, SEQUENCE should 
not be executed until after an ORIGIN macro has been executed. In this case, 
ORIGIN is needed to identify the calling station so that SEQUENCE can gain 
access to the correct input counter. 



Name 


Operation 


Operands 


[symbol] 


SEQUENCE 


(no operands) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands. Five spaces must be reserved for insertion of an output 
sequence number; space is reserved by a RESERVE = operand of the line group 
DCB macro. If insufficient space is reserved, a SEQUENCE macro coded in an 
outheader subgroup is not executed, and a return code of X'04' is set in register 
15. For incoming messages, if the input sequence number in the message header 
is low, the return code is X*04', and if the number is high or if there is no valid 
decimal number in the header field being examined, the return code is X'08'. If 
the source of an incoming message is not known at the time SEQUENCE is 
reached in an inheader subgroup, the macro does not execute and a return code of 
X'OC is placed in register 15. In none of these cases is the input sequence 
counter in the appropriate terminal table entry incremented. 

Continuity of sequence numbers is maintained by the continuation and warm 
restart capabilities of the TCAM restart facihty. 



I 
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SETEOF 



The SETEOF macro 

• sets a bit in the buffer prefix to indicate an EOF message; 

• is optional in the outheader subgroup of the MH assigned to an application 
program(and should be coded in no other). 

The SETEOF macro is used to identify the last message in a data file being 
processed by an application program. When the application program receives a 
message flagged by SETEOF, the next GET or READ/CHECK it issues after the 
complete message has been received will cause control to be passed to the routine 
whose address is specified by the EODAD= operand of the application program 
input DCB for the destination queue associated with the GET or READ. Thus, 
by issuing a SETEOF macro, the user causes the application program to stop 
obtaining work units from one or more destination queues and to do whatever is 
specified by the routine located at the EODAD address. 

The SETEOF macro is issued in the outheader subgroup of the outgoing group of 
the MH handling messages routed to an application program. 

In the case of multiple-buffer headers, SETEOF must be executed for the first 
header buffer to be effective. 

SETEOF has the following format: 



Name 


Operation 


Operands 


[symbol] 


SETEOF 


[conchars[,BLANK=(YES) ]] 
Vchar; 



symbol 



conchars 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn' ' 
characters. If hexadecimal format is used, the string must be framed with X' ' or 
XLn' ' characters. 

Notes: If this operand is omitted, the SETEOF function is performed uncondition- 
ally. If the next field in the header does not match this operand, the function is 
not performed. 
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BLANK= ( YES 
' char 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as part 
of the header string, this operand also specifies whether some other hexadecimal 
character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLT ' characters. 
Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCDIC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK= YES and an eight-byte field in the header is being checked 
by this macro, a blank appearing in the fifth byte of the field will be ignored and 
the sixth through ninth bytes will be considered to be the last four bytes of the 
field (assuming that no blanks are coded in the sixth through ninth bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being com- 
pared to the string specified by conchars . 

chars specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically skips 
over the character without performing a comparison and goes on to check the next 
character in the header. If BLANK=char and char is not the EBCDIC blank 
character, the EBCDIC blank is not ignored by this macro when it is encountered 
in the header string, but is compared to the character in the corresponding space 
in the conchars string, Hke any other character. 



{ 
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symbol 



END€HAR=Uhars ) 
(opfield) 



SETEOM 



The SETEOM macro 

• allows dynamic control of the amount of data required for a logical message; 

• specifies the action to be taken with the data in a buffer following the end of 
the message; 

• allows removal of delimiting characters (end-of -message indicators); 

• is permitted only in the inblock subgroup of an MH; 

• may be coded only once in the subgroup. 

The SETEOM macro allows the user to dynamically control the amount of data in 
any message either by specifying the length or by specifying an end-of -message 
(EOM) indicator. This macro causes data in an incoming transmission sequence 
to be either blocked or deblocked. If an EOM indicator is found in a buffer, then 
two messages may be formed; that is, incoming data is deblocked to form one or 
more messages. If an EOM indicator is not found, the transmission being handled 
is processed by the incoming MH, and subsequent transmissions are processed in 
the same way until an EOM indicator is detected; that is*, multiple buffers are 
blocked to form a single message. See Handling Logical Messages in this 
chapter for a more complete description of how to use the SETEOM macro. 



Name 


Operation 


Operand 


[symbol] 


SETEOM 


[ENDCHAR= (chars )][,EOM=El'B] 

\opfielcl| 
[,LENGTH=^integer ) ,opfield2)] 

iopfieldl/ 
[,PROCESS=|YES)][,REMOVE= /YES) ] 

INO / iNO / 



Function: Name of the macro. 

Default: None. Specification optional 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the character or character string that delimits the message. 
Default: None. This operand must be specified if the LENGTH= operand is not 
specified. If the LENGTH= operand is specified, this operand is optional. 
Format: chars may be from one to eight nonblank characters specified in charac- 
ter or hexadecimal format. If character format is specified, the field must be 
framed with C ' or CLn* ' characters. If hexadecimal format is specified, the field 
must be framed with X* ' or XLn* ' characters, n must be the length of the 
characters. 

opfield is the name of a field defined by an OPTION macro containing the charac- 
ter or character string used as an EOM indicator. The first byte of the option field 
contains the length of the delimiter, followed by the delimiter. 
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Notes: If both the LENGTH= and the ENDCHAR= operands are specified, the 
message delimiter is either the length or the characters, whichever is encountered 
first. The ENDCHAR= operand cannot be coded if EOM=ETB is coded. One of 
the following return codes is passed in register 15 after this macro executes: 



Code 



Meaning 



X*00000004' An EOM indicator delimited this message. 

X'00000008' The user-specified length delimited this 

message. 
X'OOOOOOOC An EOM indicator and the user-specified 

length delimited this message. 



X'OOOOOOIO' 



No available buffer units. 



X'00000014' Buffer not processed because no option field 

was found. 



LENGTH=(Uiiteger hopfieldl) 
lopfieldU 



Function: Specifies the number of bytes in the message. 

Default: None. Must be specified if the ENDCHAR= operand is not specified. 

If the ENDCHAR= operand is specified, this operand is optional. 

Format: integer or opfieldl followed by opfield2 . integer is a decimal integer 

that may be up to 65535. opfieldl is the name of a half word defined by an 

OPTION macro, containing the length, in bytes, of the message, opfieldl is a 

halfword option field initially set to zero and used to maintain a count of the 

number of bytes already received. 

Maximum: 65535 or a hexadecimal halfword field. 

Notes: If both the LENGTH= and the ENDCHAR= operands are specified, the 

message delimiter is either the length or the characters, whichever is encountered 

first. The LENGTH= operand cannot be coded if EOM=ETB is coded. One of 

the following codes is returned in register 15 after this macro executes: 



5 



Code 



Meaning 



X*00000004' An EOM indicator delimited this message. 

X'00000008' The user-specified length delimited this 

message. 
X*OOOOOOOC' An EOM indicator and the user-specified 

length delimited this message. 



X'OOOOOOIO' 



No available buffer units. 



X'00000014' Buffer not processed because no option field 

was found. 



PROCESS= ( YES J 



Function: Specifies whether any data following an EOM indicator is to be processed 

or discarded. 

Default: PROCESS=NO 

Format: YES or NO. YES indicates that the second portion of the data is to be 

processed. NO indicates that the second portion is to be discarded; that is, the 

original message is truncated. 

Notes: When YES is specified, processing of the second portion (which is the first 
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REMOVE= JYES^ 

Uos 



E01Vf=ETB 



buffer of a new message) begins at the SETEOM macro. When the EOM indica- 
tor is encountered, a new buffer is obtained. The remaining portion of the buffer 
is moved into the new buffer that becomes a header buffer for the new message 
with the scan pointer set to the beginning of the buffer. Thus, this buffer will be 
the next buffer to be processed by this MH. The reserve space specified by the 
DCB macro is reserved in this new header buffer when it is initiaUzed. All subse- 
quent buffers of the new message also begin processing at the SETEOM macro. If 
sufficient buffer units are not available to move the remaining portion of the 
current buffer, a return code of X'lO' is set in register 15. 

NO should be used when any remaining portion of the incoming data is to be 
discarded. This means that not only the remaining portion of the current buffer is 
dropped, but all the subsequent buffers, if any, of the current message are re- 
turned to the buffer pool. 



Function: Removes EOM characters from buffers containing logical messages (or 
partial logical messages). 
Default: NO 
Format: YES or NO. 

Notes: YES causes EOM characters to be removed from incoming buffers con- 
taining parts of one or more logical messages. 

NO causes EOM characters to remain in the buffer in which they appear. NO 
must be specified if EOM=ETB is coded. 



Function: Specifies that a logical message is deUmited by an ETB (ETX, EOB) 

condition. 

Default: None. Specification optional. 

Format: EOM=ETB 

Notes: Must be coded for 2790 support. ENDCHAR= and LENGTH= operands 

cannot be coded if this operand is coded. PROCESS=YES and REMOVE=NO 

must be coded with this operand. The following code is returned in register 15 

after this macro executes: 

Code Meaning 

X'00000004' An EOM indicator delimited this message 
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SETSCAN 



The SETSCAN macro 

• explicitly moves the scan pointer forward or backward, or 

• returns in a designated register the address of the last character of a specified 
character string, or. 

e returns in register 15 the current address of the scan pointer; 

• is optional in inheader and outheader subgroups (and not permitted in any 
other subgroups); 

• may be specified more than once in the same subgroup. 

The SETSCAN macro explicitly repositions the scan pointer forward or backward 
in the buffer, if specified. After the previous macro has executed, the scan pointer 
is positioned at the last character of the field acted upon by that macro. 
SETSCAN moves the scan pointer a specified number of nonblank characters, to 
a specified character, or to the last character of a specified character string, so that 
one or more fields is skipped. The scan pointer is left at its new position. 

Alternatively, the scan pointer is not moved. Instead, either a designated charac- 
ter string is located, and the address of the last character of the string is placed in 
a specified register, or the current address of the scan pointer is placed in register 
15. 

Use of SETSCAN is optional in inheader and outheader subgroups, where it may 
be used as many times as desired. 

When an outgoing message is processed by an outheader subgroup, STARTMH i 

positions the scan pointer to the last reserve character in the buffer, or, if there are N| 
no reserve characters, to the last byte of the buffer prefix, or, if there is a machine 
EOA sequence, to the last byte of the EOA. If this is not the location of the next 
header field to be processed, the user may employ SETSCAN to move the scan 
pointer to the byte immediately preceding the next header field to be processed. 

For an inheader subgroup that handles messages from stations designated as 
operator control terminals, if LC=IN is coded in the STARTMH macro, a 
SETSCAN macro should be coded as the first functional macro of the subgroup, 
with a CODE macro being the second functional macro (CODE tests for operator 
commands). The SETSCAN macro should move the scan pointer past the Une 
control characters (not including the EOA), leaving it pointing to the byte imme- 
diately preceding the first byte of meaningful header data. 



i 
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SETSCAN has the following format: 



Name 


Operation 


Operands 


[symbol] 


SETSCAN 


fskipchars) 
(integer / 

[,blank=(yes) ] 

(char; 
[,POINT= f BACK ) ]. 

(forward/ 
[,move=/returnI] 

(KEEP ) 

[,RESULT=/(register)V| 
1(15) f 



symbol 



iskipchars ) 
integer ( 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the new location of the scan pointer, either a character string 
to be located or a number of characters to be advanced. 
Default: None. This operand must be specified. 

Format: skipchars or integer, skipchars can be one to eight nonblank characters 
in character or hexadecimal format. If character format is used, the string may be 
unframed or framed with C ' or CLn* ' characters. If hexadecimal format is used, 
the string must be framed with X' ' or XLn' ' characters, integer is a decimal 
integer in decimal format. 
Maximum: For integer , 65535. 

Notes: skipchars is the character or character string to which the scan pointer is to 
be moved when MOVE = KEEP is specified or whose address is to be placed in the 
register specified by RESULT* (register) when MOVE = RETURN is specified. If 
MOVE=KEEP is specified, SETSCAN operates across buffers until the string is 
found. If MOVE=RETURN is specified, the character string must be located in 
the current buffer; otherwise, SETSCAN does not execute and a return code is 
set. If register 15 is specified to contain the address of the string and the string is 
not found in the buffer, a code of X*00' is returned in the low-order byte of 
register 15. If another register is specified for the address of the string and the 
string is not found in this buffer, X'04' is returned in the last byte of register 15 
(see the description of MOVE=RETURN below). The pointer should not be 
moved to a position outside the header. If skipchars is specified, POINT = BACK 
may not be specified. 



integer is the number of nonblank characters to be skipped. If is specified in 
place of integer , TCAM returns the main-storage address to which the scan 
pointer is currently pointing. If an attempt is made to set the scan pointer outside 
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of the current buffer, SETSCAN does not execute and control passes to the next 
macro. If integer is coded, MOVE=KEEP is assumed by TCAM, even if 
MOVE = RETURN is coded in the macro (unless is coded in place of integer ). 
If is coded, the MOVE= and RESULT = operands are ignored. 



BLANK=(YES) 
NO 
(char ! 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
being counted or when encountered in the character string in the message header 
being compared to the string specified by the skipchars operand, or whether 
blanks are to be counted as characters or as part of the header string when en- 
countered in it. If EBCDIC blanks are to be counted as characters or as part of 
the header string, this operand also specifics whether some other hexadecimal 
character is to be ignored when skipping or when encountered in the header 
string. 

Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may be 
unframed or framed with C* ' or CLT ' characters. If hexadecimal format is 
specified, it must be framed with X* ' or XLT ' characters. 
Notes: YES specifies that the EBCDIC blank character (X*40') is to be ignored 
by the macro whenever characters are being skipped or whenever it is encountered 
in the header character string being checked against the skip character string 
specified by the skipchars operand. For example, if BLANK= YES is coded and 
an eight-byte field in the header is being checked by this macro, a blank appearing 
in the fifth byte of the field will be ignored and the sixth through ninth bytes will 
be considered to be the last four bytes of the field (assuming that no blanks are 
coded in the sixth through ninth bytes). 



.4 



NO specifies that the EBCDIC blank character is to be treated like any other 
character when characters are being skipped or whenever it is encountered in the 
header string being compared to the string specified by skipchars . 

chars specifies that the single character replacing char is to be ignored by this 
macro whenever characters are being skipped or whenever it is encountered in the 
header string being compared to the string specified by the skipchars operand. 
That is, the macro automatically skips over the character without counting or 
performing a comparison and goes on to check the next character in the header. If 
BLANK=char is coded and char is not the EBCDIC blank character, the 
EBCDIC blank is not ignored by this macro when it is encountered in the header, 
but is counted or compared to the character in the corresponding space in the 
skipchars string, like any other character. 



POINT= (back I 

j FORWARD f 



Function: Specifies whether the scan pointer is to be moved forward or backward. 
Default: POINT=FORWARD 
Format: BACK or FORWARD. 

Notes: FORWARD specifies that the scan pointer is to be moved forward. 
BACK specifies that the scan pointer is to be moved backward. If 
POINT=BACK is specified, neither skipchars nor MOVE= RETURN may be 
specified. Also when POINT = BACK is specified, the scan pointer may not be 
moved out of the buffer in which it is located; if integer is greater than the 



{ 
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number of characters preceding the scan pointer in the buffer, the macro does not 
execute and a code of X*04' is returned in the rightmost byte of register 15. 



MOVE=( return) 
I KEEP j 



Function: Specifies whether the scan pointer is to be moved to the designated 
position and not returned to its original position before the next macro is issued, 
or is to remain stationary with the specified character string being located and the 
main-storage address of the last character in the string being returned in a desig- 
nated register. 
Default: MOVE=KEEP 
Format: RETURN or KEEP. 

Notes: If integer is replaced by zero, this operand is ignored. If integer is speci- 
fied, MOVE=KEEP is assumed by TCAM even if the macro is coded 
MOVErcRETURN. 



RESULT= /(register)) 

t(L5) / 



MOVE=RETURN may not be specified if POINT=BACK is specified. 

KEEP specifies that the scan pointer is to be moved to the designated character (if 
skipchars is coded) or moved the designated number of characters (if integer is 
coded); the pointer remains in its new location until the next macro affecting the 
scan pointer is issued. 

RETURN specifies that the scan pointer is not to be moved. Instead, the speci- 
fied character string is located and the main-storage address of the last character 
in the string is returned in the register designated by the RESULT= operand. 



Function: Specifies the general register into which the main-storage address of the 

last character of the designated character string is to be placed once the string is 

located. 

Default: RESULT=(15) 

Format: A general register 2 through 11, or 15, enclosed in parentheses. 

Notes: If the desired character string is found, the address of its last character is 

placed in the register. If RESULT=(15) is coded and the character string is not 

found in this buffer (if skipchars is coded) or if the integer specified would take 

the scan pointer out of this buffer (if integer is specified), the macro does not 

execute and a code of X'OO' is returned in the rightmost byte of register 15. 

If some register other than 15 is specified and the character string is not found in 
the buffer, or the integer specified would take the scan pointer out of the buffer, 
the macro does not execute and X*04' is returned in the low-order byte of register 
15; in this case the contents of the specified register are unchanged. 

If integer is replaced by zero, this operand is ignored. 
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Example 1: 

A SETSCAN macro that causes the scan pointer to skip forward over 5 characters 
and remain in its new position: 

SETSCAN 5 , POINT=FORWARD , MOVE=KEEP 

Example 2: 

A SETSCAN macro that results in no movement by the scan pointer, but causes 
the address of the character '=' (located to the right of the pointer) to be placed 
in register 2: 

SETSCAN C' = ' ,POINT=FORWARD,MOVE=RETURN,RESULT=( 2 ) 



( 
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SLOWPOLL 



symbol 



mask 



The SLOWPOLL macro 



• delays further polling when a line error occurs; 

• is optional in an inmessage subgroup of an MH, and 

• is not permitted in any other subgroup; 

• is not permitted in an appUcation program MH; 

• may be used more than once in an inmessage subgroup; 

• may not be used for switched lines. 

SLOWPOLL suspends further polling on a given line when errors specified by the 
error mask occur. The bits specified by the error mask operand are compared to 
the setting of the bits in the message error record for this message. If specified 
bits in the message error record are on, the polling will be suspended. Specifying 
an all-zero mask or omitting the mask operand will cause unconditional execution 
of the SLOWPOLL macro. Polling will resume after the length of time specified 
in the SECONDS = operand. 

SLOWPOLL has the following format: 



Name 


Operation 


Operands 


[symbol] 


SLOWPOLL 


[mask][,CONNECT=fAND|[,SECONDS=( integer)] 
toR / \60 / 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the five-byte bit configuration used to test the message error 
record for the message (the message error record is described in Appendix B ). 
Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, framing charac- 
ter must be used. If X* ' is used, leading zeros must be coded. If XL5' ' is used, 
leading zeros may be omitted. 

Maximum: 16777215 or a five-byte, hexadecimal field. 

Note: Omitting this operand or specifying an all-zero mask causes unconditional 
execution. 



connect=(and) 



I 



Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: CONNECT=AND or CONNECT=OR. 

Notes: AND specifies that the macro is to be executed only if all the bits specified 

in the mask operand are on in the message error record. OR specifies that macro 

is to be executed if any bit specified in the mask operand is on in the message 

error record. 
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SECONDS=rinteger\ 

Function: Specifies the length of time, expressed in seconds, during which poUing 

on the line will be suspended. 

Default: SECONDS=60 

Format: Decimal integer. 

Minimum: 1 

Maximum: 65535 



.1 



< 
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TERRSET 



The TERRSET macro 

• enables the user to set a bit in the message error record; 

• is often issued before a related ERRORMSG macro, 

• is optional in inblock, inheader, inbuffer, outheader and outbuffer subgroups. 

The TERRSET macro enables the user to set on bit 20 of the message error 
record for this message. This may be used to indicate any condition for which the 
user wishes to issue an error message. A subsequent ERRORMSG macro may be 
issued specifying a mask including the user error bit. 



Name 


Operation 


Operands 


[symbol] 


TERRSET 


(no operands) 



symbol 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

There are no operands. 
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i 



symbol 



conchar 



ROUTINE^name 



TYPETABL 



The TYPETABL macro 

• builds a branch table that can be referred to by the MSGTYPE macro. 

A given message-type table named in a MSGTYPE macro is built from one or 
more TYPETABL macros. Each TYPETABL macro expands into a message-type 
character followed by the address to be branched to for that message type. The 
first TYPETABL macro of a message-type table should have the name of that 
table in the name field. The remaining TYPETABL macros for that table should 
have blank name fields and follow directly behind the TYPETABL macro having 
the table name. Within a group of TYPETABL macros, each one with a name will 
be the beginning of a new table. 



TYPETABLE has the following format: 



Name 


Operation 


Operands 


[symbol] 


TYPETABL 


conchar , ROUTINE = name 



Function: Names the macro and the message-type table. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: The single message-type comparison character. 

Default: None. Specification required. 

Format: One nonblank character in character or hexadecimal format. If character 

format is used, the character must be a single unframed character or framed with 

C* ' or CLn' \ If hexadecimal format is used, the character must be framed with 

X* ' or XLn' '. 



Function: Names a user label in the same inheader or outheader subgroup in 

which the MSGTYPE macro names the message- type table. This is the label to be 

branched to on an equal comparison. 

Default: None. Specification required. 

Format: Must conform to the rules for assembler language symbols. 
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UNLOCK 



The UNLOCK macro 

• removes a station from extended lock mode; 

• is optional in an inheader, inmessage, outheader, or outmessage subgroup. 

When a LOCK macro is used to lock a station in extended lock mode to an 
application program, the UNLOCK macro may be included in the MH to remove 
the station from extended lock mode. When coded in an inheader or outheader 
subgroup, the conchars operand may be used in conjunction with control charac- 
ters in the message header to provide the capabiUty of optional execution of 
UNLOCK. When coded in an inmessage or outmessage subgroup, the mask 
operand may be used to provide optional execution. 

The UNLOCK macro is meaningful only in the inheader subgroup of an MH 
handhng inquiry or response messages being exchanged by an appUcation program 
and a station locked to it by a LOCK macro having EXTEND coded as an oper- 
and. When the lock condition is not in effect, the macro is ignored. 

When the UNLOCK macro is issued in a inheader subgroup handling inquiry 
messages being received from a station in extended lock mode, the message 
currently being handled is routed to the destination specified in its header or by a 
FORWARD macro (and checked by a FORWARD macro) if UNLOCK is issued 
before the FORWARD macro is issued. If UNLOCK is issued after FORWARD, 
the message is routed to the application program to which the originating station 
was locked. 

The UNLOCK macro may be issued immediately following an unconditional 
LOCK macro to remove a certain message type from lock mode before the 
message is queued. For example, 

LOCK EXTEND 
UNLOCK A 

would place the station in extended lock mode for all except type A messages. 
Again, 

LOCK MESSAGE 
UNLOCK J 

would terminate message lock mode only for type J messages. 

When the UNLOCK macro is issued in an outmessage subgroup, an optional 
facility may be specified. This is the disable facility. When specified, it causes a 
switched connection to be disabled (disconnected) when the unlock is performed. 
If the locked station is on a nonswitched Une, the disable function has no effect. 

For a discussion of the lock mode and its function in a TCAM system, see the 
description of the LOCK macro. 

UNLOCK has the following format when coded in a header subgroup: 



i 
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symbol 



Name 


Operation 


Operands 


[symbol] 


UNLOCK 


[conchars[,BLANK= 


(yes) ]] 

l^char; 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 



conchars 



BLANK 



=( YES ) 

NO 

(char ) 



Function: Specifies the character or character string that, if found in the header as 
the next nonblank field, causes execution of the function. 
Default: None. Specification optional. 

Format: One to eight nonblank characters in character or hexadecimal format. If 
character format is used, the string may be unframed or framed with C ' or CLn' ' 
characters. If hexadecimal format is used the string must be framed with X' ' or 
XLn* ' characters. 

Notes: If this operand is omitted, the UNLOCK function is performed uncondi- 
tionally. If the next field in the header does not match this operand, the function 
is not performed. 



Function: Specifies whether EBCDIC blank characters are to be ignored when 
encountered in the character string in the message header being compared to the 
string specified by the conchars operand, or whether blanks are to be part of the 
header string when encountered in it. If EBCDIC blanks are to be counted as 
part of the header string, this operand also specifies whether some other hexa- 
decimal character is to be ignored when encountered in the header string. 
Default: BLANK=YES 

Format: YES, NO, or char, char is a single character that may be specified in 
either character or hexadecimal format. If character format is specified, it may 
be unframed or framed with C ' or CLl ' ' characters. If hexadecimal format is 
specified, it must be framed with X' ' or XLl' ' characters. 
Notes: This operand is meaningless unless the conchars operand is also specified. 

YES specifies that the EBCIDC blank character (X'40') is to be ignored by this 
macro whenever it is encountered in the header character string being checked 
against the control character string specified by the conchars operand. For 
example, if BLANK=YES is coded and an eight -byte field in the header is being 
checked by this macro, a blank appearing in the fifth byte of the field will be 
ignored and the sixth through ninth bytes will be considered to be the last four 
bytes of the field (assuming that no blanks are coded in the sixth through ninth 
bytes). 

NO specifies that the EBCDIC blank character is to be treated like any other 
character when it is encountered by this macro in the header string being 
compared to the string specified by conchars. 
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char specifies that the single character replacing char is to be ignored by this 
macro whenever it is encountered in the header string being compared to the 
string specified by the conchars operand. That is, the macro automatically 
skips over the character without performing a comparison and goes on to 
check the next character in the header. If BLANK=char is coded and char 
is not the EBCDIC blank character, the EBCDIC blank is not ignored by 
this macro when it is encountered in the header string, but is compared 
to the character in the corresponding space in the conchars string, like any 
other character. 

UNLOCK specified in an inheader or inmessage subgroup removes the lock 
condition for the source terminal. In an outheader or outmessage subgroup 
the lock for the destination is removed. 

UNLOCK has the following format when coded in an inmessage or out- 
message subgroup: 



Name 


Operation 


Operand 


[symbol] 


UNLOCK 


[mask][,CONNECT=f OR ) 1[,DISABLE=/N0\] 
(and/ iVESJ 



symbol 



mask 



CONNECT=iOR ) 

Jand) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Function: Specifies the five-byte, bit configuration used to test the 
message error record for the message (see message error record in 
Appendix B), 

Default: None. Specification optional. 

Format: Decimal or hexadecimal. If hexadecimal format is used, 
framing characters must be specified. If X' ' is used, leading zeros 
must be coded. If XL5' ' is used, leading zeros may be omitted. 
Maximum: 16777215 or a five-byte, hexadecimal field. 
Note: Omitting the operand, or an all-zero mask, causes uncondi- 
tional execution. 

Function: Specifies the type of logical connection to be made between the mask and 

the message error record. 

Default: CONNECT=OR 

Format: CONNECT=OR or CONNECT=AND 

Notes: AND specifies that the macro is to be executed only if all of the bits 

specified by the mask are on in the message error record. OR specifies that the 

macro is to be executed if any bit specified by mask is on the message error 

record. 



DISABLE=jNO { 
<YESJ 



Function: Specifies whether or not a switched line is to be disabled. 

Defauh: NO 

Format: DISABLE=NO or DISABLE=YES 

Notes: NO specifies that the Une is not to be disabled. YES specifies that the line 

is to be disabled (disconnected). 



( 



3 1 6 OS/MFT and OS/MVT TC AM Programmer's Guide 



Putting the MCP Together 



This chapter describes what the physical parts of the MCP are, how to arrange 
these parts in relation to each other, and how to assemble, link-edit, and execute a 
TCAM MCP. In addition, several sample MCPs are presented and explained. 

Arranging the Sections of the MCP 

An MCP has five sections: the activation and deactivation section (the INTRO, 
OPEN, READY, and CLOSE macros and some user code to determine whether 
INTRO executed satisfactorily); a data set definition section (the DCB macros 
defining the TCAM data sets and, if appUcation programs are to be run in con- 
junction with the MCP, one PCB macro for each application program); a terminal 
and line control area section (those macros associated with the invitation lists and 
the terminal table); a Message Handler section (one or more Message Handlers); 
and an optional user routine section (closed, user subroutines called by an MH, as 
well as exit routines referred to by the INTRO macro, by DCB macros, and by the 
STARTMH macro). These sections may be coded in the order just given, or in 
any other order, except that the activation and deactivation section must come 
first. Each MCP section and locations for coding directions are given below. The 
sample program in this chapter conforms to this organization. 

The PCB macro defining an application program must be included in the MCP. 
This macro is logically similar to a DCB macro and may be included in the data set 
definition section, or it may appear in any other section, except between OPTION 
macros, among macros defining the terminal table, or within an MH. 

The INVLIST macros defining invitation hsts must follow the macros defining the 
terminal table. 



Activation and Deactivation 



Data Set Definition 



Terminal and Line Control Area 



Message Handler 



Initializes, activates, and deactivates the MCP; 

Opens and closes the MCP data sets; 

Described in the chapter ylc//varmg and Deactivating the MCP. 



Defines the data sets for the TCAM line groups, message queues, and check- 
point and logging facilities; 
Described in the chapter Defining the MCP Data Sets . 



Defines the terminal table for the MCP; 

Defines the option fields associated with the terminal table entries; 

Defines the invitation Ust for each line; 

Described in the chapter Defining Terminal and Line Control Areas . 



Determines the way in which each incoming and outgoing message is to be 

processed; 

Routes each message to its proper destination, if possible; 

Informs the user of errors occurring during message transmission, routing, and 

handling; 

Described in the chapter Designing the Message Handler . 
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User Routine 



• Consists of closed, user subroutines that may be entered from an MH, or by an 
exit specified by an INTRO, STARTMH, FORWARD, ERRORMSG, or DCB 
macro; 

• Described in the section Including a Closed Subroutine of the chapter 
Designing the Message Handler. 

The description of each macro operand specifying an exit tells what TCAM passes 
to the routine associated with that exit, and what TCAM expects the exit routine 
to return. 



Assembling, Link Editing, and Executing the Message Control Program 

The assembly, link editing, and execution of a TCAM MCP is similar to the same 
steps in any other problem program running under OS. Sample job control 
statements are given in this section for these three steps; these statements are 
guidelines only. 



Assembling an MCP 



A typical control-card sequence for assembling a TCAM MCP is: 



Link Editing an MCP 



//ASSEMBLY 


JOB 


MSGLEVEL=1 


//STEP1 


EXEC 


ASMFC 


//ASM.SYSIN 


DD 


* 



MCP Source Deck 



A typical control-card sequence for Unk-editing an MCP is: 



//LINKEDIT 
//STEP1 

// 

//SYSPRINT 

//SYSUT1 

//SYSLMOD 

//SYSLIB 

//SYSLIN 



JOB 

EXEC 

DD 
DD 
DD 
DD 
DD 



MSGLEVEL=1 

PGM=IEWL,PARM='XREF, LIST, LET' , 

REGION=96K 

SYSOUT=A 

UNIT=SYSDA,SPACE=( 1024, ( 200,20 ) ) 

DSNAME=SYS1 . TCAMLIB,DISP=OLD 

DSNAME=SYS1 . TELCMLIB, DISP=OLD 



4 
% 



MCP Object Module 

NAME TCAMPROG(R) 

In this case, the MCP load module is to be placed in a private library called 
SYSl.TCAMLIB that has previously been created by the user. 

The SYSLIB DD statement names SYSl.TELCMLIB, a special library area 
defined at system generation time. TCAM's resident modules are located in 
SYSl.TELCMLIB. 

The MCP load module resulting from the link-edit may be stored in 
SYSLLINKLIB, or in a private library such as SYSl.TCAMLIB in the example. 



Executing an MCP 



The TCAM MCP is usually executed as the highest-priority task in the highest- 
priority partition or region in the system. The TCAM MCP is executed either by 
placing the appropriate job control statements in the card reader and using an OS 
Reader/Interpreter to place the job in the system, or by issuing from the console a 
START command referring to a cataloged procedure that contains the necessary 



i 
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//EXECMCP 


JOB 


//GOSTEP 


EXEC 


//STEPLIB 


DD 


//DD1050 


DD 


// 


DD 


// 


DD 


//DD2740 


DD 


// 


DD 


// 


DD 


//DISKDD 


DD 


//SYSABEND 


DD 



job control statements. (Starting by a START command is discussed below.) The 
job control statements needed for the execute step are similar for both cases. 

A typical control card sequence for executing an MCP is as follows (in this case, 
the MCP has two Une group data sets containing three Hnes each and a message 
queues data set residing on disk; no checkpoint or logging facihty is included). 
The load-module form of the MCP is placed on SYSl.TCAMLIB by the linkage 
editor. 

EXECUTE MCP' ,MSGLEVEL=1 

PGM=TCAMPROG , REGION^ 1 OOK 

DSNAME=SYS1 . TCAMLIB, DISP=SHR 

UNIT=025 

UNIT=026 

UNIT=027 

UNIT=015 

UNIT=016 

UNIT=017 

DSNAME=DISKDS , DISP=OLD 

SYSOUT=A 

The DISKDD DD statement is for a message queues data set residing on disk; 
DISKDD is the name specified in the DDNAME= operand of the DCB macro for 
this data set, while DISKDS is the name of the data set as specified by the 
DSNAME= operand of the lEDQDATA DD statement for the lEDQXA utihty 
used to Preformat disk message queues data sets residing on disk. 

Information on the DD statements for line group data sets and message queues 
data sets is found in the chapter Defining the MCP Data Sets . 

The STEPLIB DD statement defines SYSl.TCAMLIB, the private library on 
which the MCP was placed by the linkage editor. If the Hnkage editor had placed 
the MCP in SYSLLINKLIB, no such DD statement would be needed. As an 
alternate to the STEPLIB DD statement, a JOBLIB DD statement could define 
the private library. The JOBLIB statement would immediately follow the JOB 
statement, and would be coded as follows: 

//JOBLIB DD DSNAME=SYS1 . TCAMLIB, DISP=SHR 

Defining the private library by a STEPLIB DD statement is necessary if the MCP 
is running under MVT and is to be started by a START command. A JOBLIB DD 
statement may not be included in a cataloged procedure in SYSLPROCLIB, 
while a STEPLIB DD statement may be so included in an MVT system (see the 
next section). 

Starting the MCP by a Cataloged Procedure: The user may catalog his job control 
statements for the execute step by using the lEBUPDTE utiUty program to place 
the statements in SYSLPROCLIB. (lEBUPDTE is described in the OS publica- 
tion, Utilities .) In order to start or restart his MCP, the user need only issue a 
START command from the system console naming his cataloged procedure. (Use 
of the START command for this purpose is described in the OS publication. 
Operator's Guide.) 

In the following example, three procedures are cataloged. The first of these, 
named PROCl, causes an MCP, named MCPl and located in SYSLLINKLIB, to 
k be started. The second and third procedures, named PROC2 and PROC3, both 

cause another MCP, named MCP2 and located in a private library named 
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SYSl.TCAMLIB, to be started. The difference between PROC2 and PROC3 is 
in the line configurations specified; PROC2 contains DD statements for one Une 
group data set, while PROC3 contains DD statements for two line group data sets. 
In the initialization section of MCP2 the user has coded OPEN macros for both 
data sets, and has also coded DCB macros for both data sets. When PROC2 is 
used to start MCP2, the OPEN macros for the extra Une group data set and the 
DCB macro for this data set do not execute since no DD statement is present for 
this data set; but control passes to the next instruction in each case, and the MCP 
will be started. Thus, by specifying his cataloged procedures the user can choose 
between MCPs, or between different line configurations for the same MCP, at 
start-up time. 



To get MCP2 with two line groups, at start-up time the user would enter 

STARTPR0C3.ID 

at the system console (ID is the identification sequence that must be specified by 
TCAM Modify commands entered at the system console; see the section 
Specifying Operator Commands in Using TCAM Service Facilities). 



//STARTPGM 


JOB 


MSGLEVEL=1 






// 


EXEC 


PGM=IEBUPDTE 






//SYSPRINT 


DD 


SYSOUT=A 






//SYSUTl 


DD 


DSNAME=SYS1 .PROCLIB, 


,DISP= 


=OLD 


//SYSUT2 


DD 


DSNAME=SYS1 .PROCLIB, 


.DISP= 


=OLD 


//SYSIN 


DD 


DATA 






./ 


ADD 


NAME=PR0C1 ,LIST=ALL 






./ 


NUMBER 


NEW1=10,INCR=20 






// 


EXEC 


PGM=MCP 1 






//DD1050 


DD 


UNIT=015 






// 


DD 


UNITED 16 






// 


DD 


UNIT=017 






//SYSABEND 


DD 


SYSOUT-A 






./ 


ADD 


NAME=PR0C2 , LIST=ALL 






./ 


NUMBER 


NEW1=10,INCR=20 






// 


EXEC 


PGM=MCP2 






//STEPLIB 


DD 


DSNAME=SYS1 .TCAMLIB, 


,DISP= 


=SHR 


//DD2770 


DD 


UNIT=021 






// 


DD 


UNIT=022 






// 


DD 


UNIT=023 






//SYSABEND 


DD 


SYSOUT=A 






./ 


ADD 


NAME=PR0C3 , LIST^ALL 






./ 


NUMBER 


NEW1=10,INCR=20 






// 


EXEC 


PGM=MCP2 






//STEPLIB 


DD 


DSNAME=SYS1 .TCAMLIB, 


,DISP= 


=SHR 


//DD1050 


DD 


UNIT=015 






// 


DD 


UNIT=016 






// 


DD 


UNIT=017 






//DD2770 


DD 


UNIT=021 






// 


DD 


UNIT=022 






// 


DD 


UNIT=023 






//SYSABEND 


DD 


SYSOUT=A 






./ 


ENDUP 









Sample MCPs 



This section presents three sample Message Control Programs (MCPs) together 
with associated application programs and JCL statements. The examples consisi 
of an MCP to switch messages between terminal types, an MCP with an applica 
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tion program to demonstrate inquiry and response, and an MCP with two applica- 
tion programs showing both file updating with checkpoint coordination and 
\ message retrieval. 

The programs are designed to run under MVT on a 512K IBM System/360 Model 
50. The LKED procedure used in the programs for inquiry/response and file 
updating has been modified to Unk-edit modules to a private library named 
SYSl.TCAMLIB rather than to SYSl.LINKLIB, the standard linkage library. 

The first two programs run in a single region; the third needs three regions. 
Terminal requirements are included in the explanation preceding each MCP. The 
application programs provided are guideUnes only and therefore do not demon- 
strate real processing. 

Message Switching Between Terminal Types 

Figure 25 presents an MCP designed to switch messages between IBM 1050 Data 
Communication Systems. This MCP assumes two nonswitched 1050s on a 
multipoint line and a switched 1050 on another line. The addressing and invita- 
tion characters used in the TERMINAL and INVLIST macros, and the unit 
addresses on the DD JCL statements are installation-dependent. The values 
specified in this sample program are to be used as guideUnes only. 

The MCP is written to run in two steps. The first step is an assembly creating an 
object deck. If the assembly is successful, the second step is a **link edit and go" 
using the object deck obtained from the assembly. 

In addition to message switching, this sample program permits use of the operator 
\ control facility. Operator commands may be entered either from the system 

r console or from the 1050 terminal named NYCl. 

The format of a message entered in the system depends on whether it is a message 
to be switched or an operator command. If it is an operator command it must 
begin with the four characters OPID. If it is a message to be switched, its format 
is: 

leading data X destination = data EOT 

Since the translation table is 1050, the destination name and the X must be 
entered in uppercase. The message must end with an EOT character. Examples 
of messages entered and responses received are: 

a. Entered at NYC2, a message to be switched 

X CHGO = message data newline EOT 
When CHGO calls in, it receives the response 
X CHGO = 0001 message data newline BOT 

b. Entered at NYCl, an operator command 

OPID D TP,PRITERM newline EOT 
Received at NYC 1 , the response 
IED041I PRIMARY=SYSCON 

Since all of the required INTRO operands are not specified in the assembly, the 
WTOR message 

IED002A SPECIFY TCAM PARAMETERS 
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will be received when the GO step is executed. A minimum response is S=C,U. 
Any other INTRO operands with short keyword equivalents may be altered at this 
time. Any operands not specified in the assembly but required for this execution 
(for instance, fewer cross-reference entries, a system interval, or removal of 
on-line test) may also be specified as part of the response to the WTOR. 

Each section of the sample program is commented to provide an explanation of 
the macros used and the operands specified. 



i 
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//ASMMSGSW JOB MSGLEVEL=1 

// EXEC ASMFC , PARM . ASM= ' NOLOAD , DECK ' 

//ASM.SYSIN DD * 

MSGSWTCH CSECT 

PRINT NOGEN 



** ACTIVATION AND DEACTIVATION SECTION 
* 

THIS SECTION INITIALIZES THIS MESSAGE CONTROL PROGRAM (INTRO MACRO), 
OPENS THE MCP DATA SETS ( OPEN MACROS ) , ACTIVATES THE MCP ( READY 
MACRO ) , CLOSES THE MCP DATA SETS ( CLOSE MACROS ) AND DEACTIVATES THE 
PROGRAM (RETURN MACRO). SIXTY BUFFER UNITS ( LNUNITS + MSUNITS ) ARE 
DEFINED, AND THE LENGTH OF EACH BUFFER UNIT IS SET AT 11 6 BYTES 
(KEYLEN). THE NUMBER OF UNITS PER BUFFER IS DEFINED IN THE DCB MACROS 

* IN THE DATA SET DEFINITION SECTION. THE TYPE OF STARTUP ON INTRO HAS 

* BEEN OMITTED FROM THE MACRO TO PERMIT ALTERNATE SPECIFICATION AND 
ADDITION OF OPERANDS AT EXECUTION. TWO LINE GROUPS (CONSISTING 
OF ONE LINE EACH) AND A MESSAGE QUEUES DATA SET ON REUSABLE DISK 
ARE OPENED. 



* 
* 

TCAMINIT INTRO CPB=2 , 

DISK=YES, 



CHANNEL PROGRAM BLOCKS 
DISK QUEUING UTILIZED 

PROGID=MESSAGE/SWITCHING, PROGRAM IDENTIFICATION 

LNUNITS=40, 

MSUNITS=20, 

KEYLEN=1 16, 

CR0SSRF=2, 

TRACE=10, 

DTRACE=100, 

C0NTR0L=0PID 



15,15 
OPENDISK 



ABEND 12 3, DUMP 



(DISK,( INOUT) ) 

DISK+48,DCB0FLGS 

NOEXEC 



LTR 
BZ 

NOEXEC 
* 

OPENDISK OPEN 

TM 

BNO 
* 

OPENLINE OPEN 

TM 

BNO 
* 

TM 
BNO 
* 

ALLSWELL READY 

FINISHUP CLOSE ( GROUPONE , , GROUPTWO ) 

CLOSE DISK 

L 13,4(13) 

RETURN (14,12) 



* 

* 

UNITS ASSIGNED TO LINES * 
UNITS ASSIGNED TO MAIN STORAGE* 
SIZE OF BUFFER UNITS * 

CROSS REFERENCE— DEBUG AID * 
I/O TRACE--DEBUG AID * 

SUBTASK TRACE--DEBUG AID * 
ID SEQUENCE FOR OPERATOR 
COMMANDS 

TEST IF INTRO EXECUTED 
PROPERLY 



IF NOT, ABNORMAL EXIT 

OPEN DISK QUEUE BEFORE LINES 
OPEN SUCCESSFUL 
NO - ABEND 



( GROUPONE , ( INOUT ) , GROUPTWO , ( INOUT ) ) OPEN LINE GROUPS 

GROUPONE+48 , DCBOFLGS 

NOEXEC 



GROUPTWO+48 , DCBOFLGS 
NOEXEC 



OPEN SUCCESSFUL 
NO - ABEND 

OPEN SUCCESSFUL 
NO ^- ABEND 

BEGIN PROCESSING 

CLOSE LINE GROUPS BEFORE DISK 

CLOSE DISK DATA SET 

RETURN CONTROL TO OS 

SUPERVISOR 



Figure 25. Sample Message-Switching Program (Part 1 of 5) 
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** DATA SET DEFINITION SECTION 
* 

THIS SECTION DEFINES THE DATA SETS FOR THE TCAM LINE GROUPS AND THE 
MESSAGE QUEUES ON DISK. THE DISK MESSAGE QUEUES DATA SET IS DEFINED 
TO BE REUSABLE. BOTH LINE GROUPS ARE IBM 1050 DATA COMMUNICATION 
SYSTEM GROUPS. DYNAMIC BUFFER ALLOCATION IS NOT SPECIFIED FOR 
EITHER GROUP. THEY BOTH USE THE SAME MESSAGE HANDLER ( MH ) . BUFFERS 
ARE BUILT WITH SINGLE BUFFER UNITS (BUFSIZE=116, AS IS KEYLEN ON 
THE INTRO MACRO). 



He 

* 
* 
* 

DISK 



DCB 



GROUPONE DCB 



GROUPTWO DCB 



DSORG=TQ, 
MACRF=(G,P), 
OPTCD=R, 
DDNAME=DISKDD 

DSORG=TX, 

MACRF=(G,P), 

CPRI=E, 

DDNAME=DDONE , 

TRANS=1050, 

SCT=1050, 

MH=SWITCHMH, 

INVLIST=(LISTONE), 

PCI=(N,N), 

BUFSIZE=1 16, 

BUFIN=2, 

BUF0UT=4 , 

BUFMAX=4 , 

RESERVE=(21 ,0,0,0) 

DSORG=TX, 

MACRF=(G,P), 

CPRI=S, 

TRANS=1050, 

SCT=1050, 

DDNAME=DDGRPTWO , 

jyiH=SWITCHMH, 

INVLIST=(LISTTWO), 

PCI = (N,N), 

BUFSIZE=116, 

BUFIN=2, 

BUF0UT=4 , 

BUFMAX=4 , 

RESERVE=( 21,0,0,0) 



ORGANIZATION IS TCAM DISK * 
REQUIRED OPERAND * 

DATA SET ON REUSABLE DISK * 
NAME OF ASSOCIATED DD JCL 
STATEMENT 

ORGANIZATION IS TCAM LINE 
REQUIRED OPERAND 
SEND/RECEIVE PRIORITY EQUAL 
NAME OF DD JCL STATEMENT 
1050 TRANSLATION TABLE 
SPECIAL CHARACTER TABLE 
MESSAGE HANDLER FOR LINE 
INVITATION LIST FOR LINE 
NO DYNAMIC ALLOCATION 
SIZE OF A BUFFER 
INITIAL ASSIGNMENT FOR INPUT 
INITIAL ASSIGNMENT FOR OUTPUT * 
MAXIMUM BUFFERS PER LINE * 
RESERVED FOR INSERTION OF 
DATA IN MESSAGES 

DCB FOR SECOND LINE GROUP * 

* 

SEND HAS PRIORITY OVER RECEIVE* 

He 

« 

He 
He 
He 
He 
* 
He 
He 



Figure 25. Sample Message-Switching Program (Part 2 of 5) 
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** TERMINAL AND LINE CONTROL AREA 

* THIS SECTION DEFINES THE TERMINAL TABLE FOR THE MCP , THE ENTRIES 

* IN THE TERMINAL TABLE, AND THE INVITATION LISTS FOR EACH LINE. THE 

* TERMINALS NYC1 AND NYC2 ARE ASSOCIATED WITH THE LINE GROUP DEFINED 

* BY THE GROUPONE DCB, WHILE CHGO IS THE ONLY LINE IN THE GROUPTWO 
LINE GROUP. QUEUING IS BY TERMINAL FOR EACH TERMINAL, AND USES 
MAIN-STORAGE QUEUING WITH REUSABLE DISK BACKUP. NYCl IS DEFINED 
AS A SECONDARY OPERATOR CONTROL TERMINAL: THUS NYC1 AND THE SYSTEM 
CONSOLE ARE THE ONLY TERMINALS CAPABLE OF ENTERING OPERATOR 
COMMANDS. SINCE PRIMARY= WAS NOT SPECIFIED ON THE INTRO MACRO, 
THE SYSTEM CONSOLE IS THE PRIMARY OPERATOR CONTROL TERMINAL 
FOR THIS MCP. 



* 
* 

* 
* 



NYC1 



NYC2 



CHGO 



TTABLE LAST=CHGO 
TERMINAL QBY=T, 

DCB=GROUPONE , 
RLN= 1 , 
TERM=1050, 
QUEUES=MR, 
ADDR=6402, 
ALTDEST=NYC2 , 
SECTERM=YES 
TERMINAL QBY=T, 

DCB=GROUPONE , 

RLN=1 , 

TERM=1050, 

QUEUES=MR, 

ADDR=6202, 

ALTDEST=NYC1 , 

SECTERM=NO 

TERMINAL QBY=T, 

DCB=GROUPTWO, 

RLN=1 , 

TERM=1050, 

QUEUES=MR, 

ADDR=6202, 

DIALNO=NONE 



THE LAST ENTRY IN THE TABLE 

QUEUING BY TERMINAL * 

ASSOCIATED DCB * 

RELATIVE LINE NUMBER * 

TYPE OF TERMINAL * 

MAIN STORAGE, REUSABLE DISK * 

ADDRESSING CHARACTERS * 

ALTERNATE DESTINATION * 
SECONDARY OPERATOR CONTROL 

SECOND TERMINAL IN GROUP * 

* 

* 

NOT AN OPERATOR CONTROL 

TERMINAL 

TERMINAL FOR GROUPTWO * 

* 
* 
* 
* 

MAY NOT BE CALLED BY THE 
CENTRAL PROCESSING UNIT 
BOTH ENTRIES ARE ACTIVE 



LISTONE 
LISTTWO 



UTERM=YES 
INVLIST ORDER=(NYC1+640B,NYC2+620B) GROUPONE INVITATION LIST 
INVLIST ORDER=(CHGO+620B) GROUPTWO INVITATION LIST 



Figure 25. Sample Message-Switching Program (Part 3 of 5) 
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* 

** MESSAGE HANDLER SECTION 
* 

THIS SECTION PROVIDES THE MESSAGE-SWITCHING CAPABILITY OF THE MCP . 
INCOMING MESSAGES ARE TRANSLATED TO EBCDIC AND CHECKED TO SEE IF 
THEY ARE OPERATOR COMMANDS. IF SO THEY ARE PROCESSED BY THE OPERATOR 
CONTROL FUNCTION. IF THEY ARE NOT, THE 'DATE AND TIME IS INSERTED IN 
THE MESSAGE (USING 16 OF THE 21 BYTES RESERVED BY THE "RESERVE^" 
OPERAND IN THE DCB ) AND THE MESSAGE IS FORWARDED TO THE DESTINATION 
SPECIFIED IN THE HEADER. OUTGOING MESSAGES ARE SEQUENCED (USING THE 
REMAINING RESERVED CHARACTERS), TRANSLATED BACK TO 1050 LINE CODE 
AND SENT. 



* 

* 
* 
* 

He 

* 
* 

sic 4( H( )K H( 

SWITCHMH STARTMH LC=OUT 
* 

* INCOMING GROUP OF THE MH 
* 

INGROUP INHDR 

CODE , 
SETSCAN 



X 
FORWARD ( 4 ) 



INEND 



REMOVE LINE CONTROL 



PROCESS HEADERS ONLY 

TRANSLATE TO EBCDIC 

SET SCAN POINTER TO AN X 

FORWARD TO THE DESTINATION 

NAMED IN THE NEXT FOUR BYTES 

OF THE MESSAGE 

END OF THE INCOMING GROUP 



* OUTGOING GROUP OF THE MH 



OUTGROUP OUTHDR 

SETSCAN - 
SEQUENCE 
CODE , 
OUTEND 



PROCESS HEADERS ONLY 
SET SCAN POINTER TO AN = 
INSERT SEQUENCE NUMBER 
TRANSLATE TO 1050 LINE CODE 
END OF THE OUTGOING GROUP 



,1 



DCBOFLGS 



EQU 
END 



X' 10' 



Figure 25. Sample Message-Switching Program (Part 4 of 5) 
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//LKGMSGSW JOB MSGLEVEL=1 ,REGI0N=1 20K,TYPRUN=HOLD 
//S2 EXEC LKEDG 

//LKED.SYSLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 
//LKED.SYSIN DD * 

OBJECT DECK HERE 



//GO.STEPLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 
//GO.DISKDD DD DSNAME=SAMP1 ,DISP=SHR 
//SYSPRINT DD SYSOUT=A 
//SYSABEND DD SYSOUT=A 
//GO.DDONE DD UNIT=015 
//GO.DDGRPTWO DD UNIT=011 



Figure 25. Sample Message-Switching Program (Part 5 of 5) 
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Inquiry and Response \ 

Figure 26 presents an MCP designed to use the conversational capabilities of 
TCAM. This MCP locks a terminal to an application program from the time a 
message is entered until a response is provided. A sample application program is 
also provided, but its functions are limited to recognition of messages. It does not 
do any processing. 

The MCP assumes two nonsvi^itched IBM 1050 Data Communication Systems on 
a multipoint line, and a single switched 1050 on another line. The addressing and 
invitation characters used in the TERMINAL and INVLIST macros, and the unit 
addresses on the DD JCL statements are installation-dependent. The values 
specified in the sample programs are guidelines only. 

The programs are written to run in three steps. The MCP and the application 
program are first assembled and object decks are obtained. If there are no 
assembly errors, the object decks are link-edited. The final step is the execution 
of the MCP, which will attach the application program after the MCP data sets are 
open. 

The inquiry and response feature has a limiting effect on transmission in the 
multipoint line group. If one of the terminals on the line enters a message, the 
other is locked out (cannot enter data) until the response has been received by the 
originating terminal. The terminal on the other line may enter messages during a 
lock on the multipoint Une. The message format for the example is: 

origin b sequence fe = b data b /( 1 6 b )EOT ^ 

If the origin and sequence fields are valid, the response is: ^ 

origin b date b time b sequence b = out-sequence b data b/ 

MESSAGE RECEIVED EOT 
If the origin field was incorrectly specified, the response is: 

ORIGIN FIELD WRONG 

If the sequence number was incorrectly specified, the response is: 

origin bdatebtimeb sequence SEQUENCE NUMBER HIGH 

or 

origin bdatebtimeb sequence SEQUENCE NUMBER LOW 

Since the translation table used is 1050, the origin field must be entered in upper- 
case characters. 

The MCP includes the operator control facility. Operator commands may be 
entered from the system console or from the terminal named NYCl. If an opera- 
tor command is entered at NYCl, it must begin with the four-character identifier 
OPID. 

Since all of the required INTRO operands are not specified in the assembly of the 
MCP, a WTOR message 



IED002A SPECIFY TCAM PARAMETERS 



will be received at the system console when the GO step is executed. The mini- 
mum required response is 'S=C,U'. Any other INTRO operands with short 



( 
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keyword equivalents may be altered, and operands not specified in the assembly 
but required for this execution may also be specified as part of the response to the 
WTOR. 

Each section of the sample MCP and the application program that follows it has 
been commented to provide explanation of the macros used and the operands 
specified. 
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//ASMINQ JOB MSGLEVEL=1 

// EXEC ASMFC, FARM. ASM='NOLOAD, DECK' 

//ASM.SYSIN DD * 

INQUIRY CSECT 

PRINT NOGEN 

* 

** ACTIVATION AND DEACTIVATION SECTION 
* 

THIS SECTION INITIALIZES THE MESSAGE CONTROL PROGRAM (INTRO MACRO), 
OPENS THE MCP DATA SETS (OPEN MACRO), ATTACHES THE APPLICATION 
PROGRAM (ATTACH MACRO), ACTIVATES THE MCP (READY MACRO), CLOSES THE 
MCP DATA SETS (CLOSE MACRO), AND DEACTIVATES THE PROGRAM (RETURN 
MACRO). SIXTY BUFFERS ( LNUNITS + MSUNITS ) ARE DEFINED, AND THE 
LENGTH OF EACH BUFFER UNIT SET AT 11 6 ( KEYLEN ) . THE NUMBER OF UNITS 
PER BUFFER IS DEFINED IN THE DCB MACROS IN THE DATA SET DEFINITION 
SECTION. THE TYPE OF STARTUP ON INTRO HAS BEEN OMITTED FROM THE 
MACRO TO PERMIT ALTERNATE SPECIFICATION AND ADDITION OF OPERANDS AT 
EXECUTION. TWO LINES ARE OPENED. 



* 
* 

* 

* 
* 

TCAMINIT INTRO DISK=NO, NO DISK QUEUING * 

PROGID=INQUIRY/RESPONSE, PROGRAM IDENTIFICATION * 

LNUNITS=40, BUFFERS ASSIGNED TO LINES * 

MSUNITS=20, BUFFERS ASSIGNED TO MAIN STOR * 

KEYLEN=116, SIZE OF BUFFER UNITS * 

CR0SSRF=2, CROSS-REFERENCE - DEBUG AID * 

TRACE=10, I/O TRACE - DEBUG AID * 

DTRACE=100, SUBTASK TRACE - DEBUG AID * 

CONTROL=OPID ID SEQUENCE FOR OPERATOR 

* CONTROL MESSAGES 

15,15 TEST IF INTRO EXECUTED 

OPENLINE PROPERLY 



ABEND 12 3, DUMP 



( GROUPONE , ( INOUT ) ,GROUPTWO, ( INOUT ) ) OPEN LINE GROUPS 



LTR 
BZ 

NOEXEC 

OPENLINE OPEN 

TM 

BNO 
* 

TM 
BNO 

ATTACH EP=INQAP 
READY 
FINISHUP CLOSE ( GROUPONE ,, GROUPTWO ) 
L 13,4(13) 
RETURN (14,12) 



IF NOT, ABNORMAL EXIT 



GROUPONE+48 , DCBOFLGS 
NOEXEC 

GROUPTWO+48 , DCBOFLGS 
NOEXEC 



OPEN SUCCESSFUL 
NO - ABEND 

OPEN SUCCESSFUL 
NO - ABEND 

ATTACH APPLICATION PROGRAM 
BEGIN PROCESSING 
CLOSE LINE GROUPS 
RETURN CONTROL TO OS 
SUPERVISOR 



Figure 26. Sample Inquiry/Response Program (Part 1 of 9) 
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* 

* 

** DATA SET DEFINITION SECTION 

THIS SECTION DEFINES THE DATA SETS FOR THE TCAM LINE GROUPS AND THE 
PROCESS CONTROL INTERFACE. BOTH LINE GROUPS ARE IBM 1050 DATA 
COMMUNICATION SYSTEM GROUPS. DYNAMIC BUFFER ALLOCATION IS NOT 
SPECIFIED FOR EITHER GROUP. THEY BOTH USE THE SAME MESSAGE HANDLER 
(MH). BUFFERS ARE BUILT WITH SINGLE BUFFER UNITS. THE PROCESS 
CONTROL BLOCK REFERS TO A DIFFERENT MH . SINCE THE APPLICATION 
PROGRAM GETS AND PUTS MESSAGES, THE BUFFER SIZE FOR THE PROCESS 
CONTROL BLOCK IS THE SAME AS THAT FOR THE LINES. 



* 
* 
* 

GROUPONE DCB 



GROUPTWO DCB 



QPROC 



PCB 



DSORG=TX, 


ORGANIZATION IS TCAM LINE 


* 


MACRF=(G,P), 


REQUIRED OPERAND 


* 


CPRI=E, 


SEND/RECEIVE PRIORITY EQUAL 


♦ 


DDNAME=DDGRPONE , 


NAME OF DD JCL STATEMENT 


♦ 


TRANS=1050, 


1050 TRANSLATION TABLE 


♦ 


SCT=1050, 


SPECIAL CHARACTERS TABLE 


« 


MH=LINEMH, 


MESSAGE HANDLER FOR LINE 


« 


INVLIST=(LISTONE), 


INVITATION LIST FOR LINE 


* 


PCI = (N,N), 


NO DYNAMIC BUFFER ALLOCATION 


* 


BUFSIZE=116, 


SIZE OF A BUFFER 


* 


BUFIN=2, 


INITIAL ASSIGNMENT - INPUT 


♦ 


BUF0UT=4 , 


INITIAL ASSIGNMENT - OUTPUT 


« 


BUFMAX=4 , 


MAXIMUM BUFFERS PER LINE 


« 


RESERVE=(21 ,0,0,0) 


RESERVED FOR INSERTION OF 
DATA IN MESSAGES 




DSORG=TX , 


DCB FOR SECOND LINE GROUP 


« 


MACRF=(G,P), 




♦ 


CPRI=S, 


SEND HAS PRIORITY OVER RECEIVE* 


DDNAME=DDGRPTWO , 




♦ 


TRANS=1050, 




« 


SCT=1050, 




« 


MH=LINEMH , 




* 


INVLIST=(LISTTWO), 




« 


PCI = (N,N), 




« 


BUFIN=2, 




♦ 


BUF0UT=4 , 




« 


BUFMAX=4 , 




* 


RESERVE=(21 ,0,0,0) 






MH=APPMH , 


PROCESS CONTROL BLOCK 


an 


BUFSIZE=116, 




« 


BUFIN=5, 




* 


BUF0UT=5 , 




♦ 


RESERVE=(5,0) 







Figure 26. Sample Inquiry/Response Program (Part 2 of 9) 
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* 

** TERMINAL AND LINE CONTROL SECTION 
* 

* THIS SECTION DEFINES THE TERMINAL TABLE FOR THE MCP, THE ENTRIES IN 

* THE TERMINAL TABLE, AND THE INVITATION LISTS FOR EACH LINE. THE 

* TERMINALS NYC1 AND NYC2 ARE ASSOCIATED WITH THE LINE GROUP DEFINED 
BY THE GROUPONE DCB, WHILE CHGO IS THE ONLY LINE IN THE GROUPTWO 
LINE GROUP (THIS IS A SWITCHED LINE, GROUPONE IS NON-SWITCHED). 
QUEUING IS BY TERMINAL FOR EACH TERMINAL, AND USES MAIN-STORAGE ONLY 
QUEUING. NYC1 IS DEFINED AS A SECONDARY OPERATOR CONTROL TERMINAL. 
TWO PROCESS ENTRIES ARE ALSO DEFINED, ONE FOR GET PROCESSING AND 
THE OTHER FOR PUT. QUEUING FOR THE GET PROCESSOR IS MAIN-STORAGE 
ONLY, AND IT IS DEFINED AS ITS OWN ALTERNATE DESTINATION. 
BOTH PROCESS ENTRIES REFER TO THE SAME PROCESS CONTROL BLOCK ( PCB ) . 



* 
* 
* 
* 
* 

* 
* 



GPRC 



PPRC 
NYC1 



NYC2 



* 

CHGO 



LAST ENTRY IN THE TABLE 
PCB NAME 

MAIN-STORAGE ONLY QUEUING 
ALTERNATE DESTINATION 
PUT PROCESS ENTRY 
QUEUING BY TERMINAL 
ASSOCIATED DCB 
RELATIVE LINE NUMBER 
TYPE OF TERMINAL 
MAIN-STORAGE ONLY QUEUES 
ADDRESSING CHARACTERS 
SIZE OF A BLOCK 
SECONDARY OPERATOR CONTROL 
TERMINAL 
SECOND TERMINAL IN GROUPONE 



LISTONE 
LISTTWO 



TTABLE LAST=CHGO 
TPROCESS PCB=QPROC, 

QUEUES=MO, 

ALTDEST=GPRC 
TPROCESS PCB=QPROC 
TERMINAL QBY=T, 

DCB=GROUPONE , 

RLN=1 , 

TERM=1050, 

QUEUES=MO, 

ADDR=6402, 

NTBLKSZ=( 116), 

SECTERM=YES 

TERMINAL QBY=T, 

DCB=GROUPONE , 
RLN=1 

TERM=1050, 
QUEUES=MO, 
ADDR=6202, 
NTBLKSZ=( 116), 
ALTDEST=NYC1 , 
SECTERM=NO 

TERMINAL QBY=T, 

DCB=GROUPTWO, 

RLN= 1 , 

TERM=1050, 

QUEUES=MO, 

ADDR=6202, 

NTBLKSZ=( 116), 

DIALNO=NONE MAY NOT BE CALLED BY THE 

CENTRAL PROCESSOR 
INVLIST ORDER=(NYC1+640B,NYC2+620B) GROUPONE INVITATION LIST 
INVLIST ORDER=(CHGO+620B) GROUPTWO INVITATION LIST 



ALTERNATE DESTINATION 
NOT A SECONDARY OPERATOR 
CONTROL TERMINAL 
TERMINAL FOR GROUPTWO 



* 



* 
* 
* 
* 
* 
* 
* 



* 
* 

He 

* 



* 
* 
* 



Figure 26. Sample Inquiry/Response Program (Part 3 of 9) 
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* 

** MESSAGE HANDLER SECTION 
* 

* THIS SECTION PROVIDES THE MESSAGE HANDLING FUNCTION OF THE MCP . 

* IT CONTAINS TWO MHS . THE FIRST RECEIVES INPUT FROM LINES AND 

* FORWARDS TO THE GET APPLICATION PROGRAM AFTER ITS ORIGIN AND 

* SEQUENCE NUMBER HAVE BEEN VERIFIED, AND THE DATE AND TIME HAVE BEEN 

* INSERTED. THE TERMINAL THAT SENT THE MESSAGE IS LOCKED TO THE 

* APPLICATION PROGRAM UNTIL A RESPONSE IS RECEIVED. MESSAGES WITH 

* INVALID ORIGIN OR SEQUENCE NUMBER ARE CANCELED, AND AN ERROR 

* MESSAGE BUILT. OUTGOING MESSAGES ARE SEQUENCED, AND AN EOB/EOT IS 

* INSERTED AT THE END OF THE MESSAGE. THE SECOND MH RECEIVES INPUT 

* FROM THE APPLICATION PROGRAM AND FORWARDS IT TO THE DESTINATION 

* PROVIDED BY THE APPLICATION PROGRAM. 

* 

* FIRST MESSAGE HANDLER - FOR LINES 
* 

LINEMH STARTMH LC=OUT, REMOVE LINE CONTROL * 

STOP=YES, STOP ON ERRORS * 

CONV=YES CONVERSE MODE REQUESTED 

INHDR TO PROCESS HEADERS 

CODE 100 CONVERT TO EBCDIC FROM 1050 

* LINE CODE 

ORIGIN 4 GET FOUR-CHARACTER ORIGIN 

* FROM MESSAGE 
DATETIME INSERT DATE AND TIME 
SEQUENCE VERIFY SEQUENCE NUMBER 
FORWARD DEST=C'GPRC' FORWARD TO GET PROCESSOR 
LOCK MESSAGE LOCK TERMINAL TO APPLICATION 

* PROGRAM UNTIL RESPONSE 
INMSG FULL MESSAGE RECEIVED 
CANCELMG X ' 5800000000 ' CANCEL MESSAGES WITH INVALID 

* ORIGINS AND SEQUENCE NUMBERS 
MSGGEN X'4000000000' , IF ORIGIN WRONG, SEND * 

CL1 8 'ORIGIN FIELD WRONG' THIS MESSAGE 
ERRORMSG X ' 1 000000000 ' , IF SEQUENCE HIGH, RETURN THIS * 

DEST=ORIGIN, MESSAGE WITH THE HEADER TO ITS* 

DATA=C • SEQUENCE NUMBER HIGH' ORIGIN 
ERRORMSG X ' 0800000000 ' , IF SEQUENCE LOW, RETURN THIS * 

DEST=ORIGIN, MESSAGE WITH THE HEADER TO ITS* 

DATA=C' SEQUENCE NUMBER LOW' ORIGIN 
INEND END OF INCOMING GROUP 

OUTHDR TO PROCESS HEADERS 

SETSCAN C'=' SET SCAN POINTER TO AN = 

SEQUENCE INSERT SEQUENCE NUMBER 

CODE , TRANSLATE BACK TO LINE CODE 

MSGFORM INSERT EOB/EOT IN MESSAGE 

OUTEND END OF OUTGOING GROUP 

* THIS MH 

* SECOND MESSAGE HANDLER - FOR APPLICATION PROGRAM 

APPMH STARTMH LC=OUT REMOVE LINE CONTROL 

INHDR TO PROCESS HEADERS 

FORWARD DEST=PUT TO DESTINATION IN HEADER 



Figure 26. Sample Inquiry/Response Program (Part 4 of 9) 
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INEND 
OUTHDR 
SETSCAN C'=' 
SETEOF C'CLOSEAP' 



OUTEND 
DCBOFLGS EQU X ' 1 ' 
END 



PROVIDED BY PUT APPLICATION 

PROGRAM 

END OF INCOMING GROUP 

PROCESS OUTGOING HEADERS 

RESET SCAN POINTER 

SET END OF FILE IF CLOSEDOWN 

MESSAGE RECEIVED 

END OF OUTGOING GROUP 



Figure 26. Sample Inquiry/Response Program (Part 5 of 9) 
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//ASMINQAP JOB MSGLEVEL=1 

// EXEC ASMFC, FARM. ASM='NOLOAD, DECK' 

//ASM.SYSIN DD * 

INQAP CSECT 

PRINT NOGEN 



** INITIALIZATION SECTION 



* THIS SECTION DOES THE NECESSARY INITIALIZATION FOR THE PROGRAM. 

* IT SAVES REGISTERS, ESTABLISHES ADDRESSABILITY AND SETS THE 

* NEW SAVE AREA ADDRESS IN THE STANDARD SAVE AREA REGISTER. 



t I 



SAVE (14,12 

LR 12,15 
USING INQAP, 12 

ST 13, SAVE+4 

LA 13, SAVE 

* 

** ACTIVATION SECTION 



SAVE REGISTERS 
RESET BASE REGISTER 
ESTABLISH ADDRESSABILITY 
SAVE ADDRESS OF SAVE AREA 
NEW SAVE AREA ADDRESS 



* THIS SECTION OPENS THE DATA SETS FOR THE PROGRAM. 
* 

^ H( 4(4( sic 

OPEN 



OPEN INPUT DCB 
OPEN OUTPUT DCB 



EQU * 
OPEN DCBIN 
OPEN DCBOUT 

** PROCESSING SECTION 

* THIS SECTION CONTROLS THE ACCESS, PROCESSING, AND RETURN OF MESSAGES, 

* IT ALSO TESTS FOR THE NEED TO CLOSE DOWN THE PROGRAM, AND CLEARS 

* WORK AREAS IF NOT. 



GET END OF WORK AREA ADDRESS 

GET A MESSAGE 

SET LENGTH COUNTER 

GET START OF MSG DATA 



* 






iic*:ic4c* 






LOOP 


EQU 


* 




LA 


10,GOTMSG 




GET 


DCBIN, WORK 




LA 


9,1 




LA 


2,WORK+8 


LOOP 2 


EQU 


* 




CLI 


0(2), CV 


^ 


BE 


PUT 




LA 


9,1(9) 




LA 


2,1(2) 




CR 


2,10 


:|c 


BE 


CLOSEM 


^ 


B 


LOOP 2 


PUT 


EQU 


* 




LA 


2,1(2) 




MVC 


0( 16,2),GOTMSG 




LA 


9,27(9) 



SEARCH FOR END OF DATA 

IF FOUND, COMPLETE PROCESSING 

INCREMENT LENGTH 
BUMP TO NEXT CHARACTER 
END AND NO / 
YES - CLOSE DOWN 

CONTINUE SEARCH 



GET PAST LAST CHARACTER 
PUT 'MSG RECEIVED' IN MSG 
ADD INSERT LENGTH 



Figure 26. Sample Inquiry/Response Program (Part 6 of 9) 
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9,DCBOUT+82 
DCBOUT,WORK 
WORK,C' ' 
W0RK-f1( 149), WORK 
LOOP 



PUT LENGTH IN LRECL FIELD 
PUT THE MESSAGE 

CLEAR WORK AREA TO BLANKS 
GET ANOTHER MESSAGE 



STH 
PUT 
MVI 
MVC 
B 
* 

** DEACTIVATION SECTION 
* 

* THIS SECTION CLOSES THE DATA SETS FOR THE PROGRAM AND RETURNS TO 

* THE OS SUPERVISOR 
* 

CLOSEM 



CLOSE INPUT DCB 

CLOSE OUTPUT DCB 

RESTORE ADDRESS OF SAVE AREA 

RETURN TO OS SUPERVISOR 



EQU * 
CLOSE DCBIN 
CLOSE DCBOUT 
L 13, SAVE+4 
RETURN (14,12) 
* 

** ERROR HANDLING SECTION 
* 

* THIS SECTION PROVIDES THE ERROR HANDLING FOR UNCORRECTABLE 

* ERRORS AND END OF DATA. 



I/O 



ERROR 



EQU 
WTO 
B 



* 

' SYNAD 
CLOSEM 



ENTERED * 



UNCORRECTABLE ERROR 
CLOSE DOWN THE PROGRAM 



END 



END OF DATA INDICATOR 
CLOSE DOWN THE PROGRAM 



EQU * 

WTO 'EODAD ENTERED' 

B CLOSEM 

** DATA SET DEFINITION SECTION 

4c 

* THIS SECTION DEFINES THE DATA SETS USED BY THE PROGRAM. 

He 

DCBIN DCB 



DCBOUT 



DCB 



DSORG=PS , 

BLKSIZE=124, 

DDNAME=APPIN, 

SYNAD=ERROR, 

EODAD=END , 

LRECL=1 16, 

OPTCD=W, 

MACRF=GM 

DSORG=PS , 

BLKSIZE=124, 

DDNAME=APPOUT , 

SYNAD=ERROR, 

LRECL=1 16, 

OPTCD=WU , 

MACRF=PM 



PHYSICAL SEQUENTIAL 
SIZE OF MESSAGE AND WORK 
NAME OF DD JCL STATEMENT 
UNCORRECTABLE ERROR HANDLER 
END OF DATA HANDLER 
SIZE OF LOGICAL RECORD 
BUILD PREFIX FOR SOURCE 
DCB FOR GET 



* 
* 

4c 
* 
4c 
4c 
4c 

4c 
4c 
4c 
4c 
4e 
4c 



DCB FOR PUT 



Figure 26. Sample Inquiry/Response Program (Part 7 of 9) 
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* 

** WORK AREA DEFINITION SECTION 

* THIS SECTION DEFINES THE WORK AREAS USED BY THE PROGRAM. 

Hi ^H HH HH Hfi 

SAVE DC 18F'0' PROGRAM SAVE AREA 

WORK DC 150C' ' WORK AREA FOR MESSAGE 

GOTMSG DC C MESSAGE RECEIVED' MESSAGE PROCESSED INDICATOR 
* 

END 



Figure 26. Sample Inquiry/Response Program (Part 8 of 9) 
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//LKDINQ JOB MSGLEVEL=1 

// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS1 .TCAMLIB,DISP=OLD ( 

//LKED. SYS IN DD * 

OBJECT DECK HERE 

NAME INQUIRY(R) 
//LKDINQAP JOB MSGLEVEL=1 
// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS1 .TCAMLIB,DISP=OLD 
//LKED.SYSIN DD * 

OBJECT DECK HERE 



NAME INQAP(R) 
//GOINQ JOB MSGLEVEL=1 ,REGION=120K,TYPRUN=HOLD 
//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 
// EXEC PGM=INQUIRY 
//GO . SYSABEND DD SYSOUT=A 
//APPIN DD QNAME=GPRC 
//APPOUT DD QNAME=PPRC 
//DDGRPONE DD UNIT=029 
//DDGRPTWO DD UNIT=021 



Figure 26. Sample Inquiry/Response Program (Part 9 of 9) 
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File Updating with Checkpoint Coordination 

Figure 27 presents an MCP that demonstrates coordination of checkpointing by 
the MCP and an appUcation program. This MCP also can switch messages and 
use the operator control facility. Finally, a second application program utilizes the 
retrieve capabilities of the POINT macro. Two lines are assumed, one a point-to- 
point line with two IBM 1050s, and the other supporting a single nonswitched 
IBM 2740. The addressing and invitation characters used in the TERMINAL and 
INVLIST macros, and the unit addresses on the DD JCL statements are 
installation-dependent. The values specified in the sample program are guidelines 
only. 

The job is set up to run in three steps. The MCP and both application programs 
are first assembled, then object decks from the first step are link-edited. As the 
final step, the MCP is executed. The MCP will prompt at the system console 
when it is time for the appUcation programs to be started. 

The format of the message depends upon the function desired. If it is a message 
to be switched, the format on input is: 

destination bSb origin b data bEOT 
If the origin is correct, the message received at the destination is: 

destination bSb origin b data 
If the origin is invalid, the message received at the source will be: 

ORIGIN FIELD WRONG 

If it is a message for the appUcation program that does the fUe update, the input 
format is: 

destination bAb sequence b data b/(16b)EOT 
For valid sequence numbers, the message received at the destination is: 

out'Sequence b destination bAb sequence b date b time b data 
If the sequence number is invalid, the message received at the source is: 

SEQUENCE NUMBER HIGH 
or 

SEQUENCE NUMBER LOW 

Messages for the retrieve application program may be formatted either: 

destination h/h data bEOT 

or 

destination bAb sequence h/h data bEOT 

where destination is the name of the process entry, and sequence is the sequence 
number of the message. The format of data in either of the two above messages: 

type 
i 



termname 

I I I I 



sequence 
number 



J_L 



where termname is an eight-byte field that is left adjusted and padded right with 
blanks, type is either character I (for input) or character O (for output), and 
sequence number is a five-byte field containing the sequence number of the 
message to be retrieved (in character, right adjusted, and padded left with zeros). 
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Operator commands entered from NYCl or CHGO must begin with the identifier 
OPID. Because of the translation tables used, messages entered by NYCl and 
NYC2 must specify destination and origin in uppercase, while the same fields 
when entered by CHGO may be in either upper or lowercase. 

Since all of the required INTRO operands were not specified in the assembly, the 
WTOR message 

IED002A SPECIFY TCAM PARAMETERS 

will be received at the console when the GO step is executed. A minimum re- 
sponse must specify some sort of restart with the S= operand. Any other oper- 
ands with a short keyword equivalent specified in the assembly may be altered, 
and any operands not specified but required for this execution may also be 
specified as part of the response to the WTOR. 

The MCP and its associated application programs are commented to provide an 
explanation of the macros used and the operands specified. 



4 
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//ASMUPDT JOB MSGLEVEL=1 

// EXEC ASMFC,PARM.ASM=' LOAD, DECK' 

//ASM.SYSIN DD * 

UPDTCKPT CSECT 

PRINT NOGEN 

4( 4c H( 9i( ^c 



** ACTIVATION AND DEACTIVATION SECTION 
* 

* THIS SECTION INITIALIZES THE MESSAGE CONTROL PROGRAM (INTRO MACRO! 

* OPENS THE MCP DATA SETS (OPEN MACROS), INDICATES THAT THE 

* APPLICATION PROGRAMS MAY BE STARTED (WTO MACRO), ACTIVATES THE 
MCP (READY MACRO), CLOSES THE DATA SETS (CLOSE MACROS) AND 
DEACTIVATES THE PROGRAM ( RETURN MACRO ) . SIXTY BUFFERS ( LNUNITS + 
MSUNITS) ARE DEFINED, AND THE LENGTH OF EACH BUFFER UNIT SET AT 
116 (KEYLEN). THE NUMBER OF UNITS PER BUFFER IS DEFINED IN THE 
DCB MACROS IN THE DATA SET DEFINITION SECTION. THE TYPE OF 
STARTUP ON INTRO HAS BEEN OMITTED FROM THE MACRO TO PERMIT 
ALTERNATE SPECIFICATION AND ADDITION OF OPERANDS AT EXECUTION. 
TWO LINE GROUPS ARE OPENED. 



* 
* 
* 

He 

* 
* 

* 



TCAMINIT INTRO CPB=2 , 

DISK=YES, 



CHANNEL PROGRAM BLOCKS 
DISK QUEUING USED 



* 

PROGID=CHECKPOINT/COORDINATION, PROGRAM IDENTIFICATION * 

BUFFERS ASSIGNED TO LINES * 

BUFFERS ASSIGNED TO MAIN STOR * 

SIZE OF BUFFER UNITS * 

CHECKPOINT EVERY 30 MINUTES * 

CKREQ MACROS IN F I LEAP * 

CROSS-REFERENCE - DEBUG AID * 







LNUNITS=40, 






MSUNITS=20, 






KEYLEN=116, 






CPINTVL=180D, 






CKREQS=2 , 






CR0SSRF=2, 






TRACE=10, 






DTRACE=100, 


^ 




CONTROL-OPID 




LTR 


15,15 


^ 


BZ 


OPENDISK 


NOEXEC 


ABEND 


123, DUMP 


OPENDISK 


EQU 


* 




OPEN 


(DISK,(INOUT) ) 




TM 


DISK+48,DCBOFLGS 


* 


BNO 


NOEXEC 




OPEN 


( CKPT , ( INOUT ) ) 




TM 


CKPT+48,DCBOFLGS 


^ 


BNO 


NOEXEC 




OPEN 


( GROUPONE , ( INOUT ) , GRi 




TM 


GROUPONE+48 , DCBOFLGS 


He 


BNO 


NOEXEC 




TM 


GROUPTWO+48 , DCBOFLGS 




BNO 


NOEXEC 



I/O TRACE - DEBUG AID 

SUBTASK TRACE - DEBUG AID 

ID SEQUENCE FOR OPERATOR 

COMMANDS 

TEST IF INTRO EXECUTED 

IMPROPERLY 

ABNORMAL EXIT 



OPEN DISK QUEUE FIRST 
OPEN SUCCESSFUL 
NO - ABEND 

OPEN CHECKPOINT QUEUE NEXT 
OPEN SUCCESSFUL 
NO - ABEND 



OPEN SUCCESSFUL 
NO - ABEND 

OPEN SUCCESSFUL 
NO - ABEND 



WTO 'TIME TO START APPLICATION PROGRAMS' 
READY BEGIN PROCESSING 



Figure 27, Sample Checkpoint Coordination Program (Part 1 of 1 1) 
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* 

* 
DISK 



CKPT 



CLOSE ( GROUPONE , , GROUPTWO ) 

CLOSE CKPT 

CLOSE DISK 

L 13,4(13) 

RETURN ( 14,12) 



DATA SET DEFINITION SECTION 



CLOSE LINE QUEUES FIRST 
CLOSE CHECKPOINT QUEUE NEXT 
CLOSE DISK QUEUE LAST 
RETURN CONTROL TO OS 
SUPERVISOR 



THIS SECTION DEFINES THE DATA SETS FOR THE TCAM DISK QUEUE, 

THE CHECKPOINT QUEUE, AND THE LINE GROUPS AND APPLICATION PROGRAM 

PROCESS CONTROL INTERFACE. ONE LINE GROUP USES TWO IBM 1050 DATA 

COMMUNICATION SYSTEMS AND THE OTHER USES THE IBM 2740 

SYSTEM. DYNAMIC BUFFER ALLOCATION IS NOT SPECIFIED FOR EITHER 

GROUP. BOTH USE THE SAME MESSAGE HANDLER ( MH ) , AND BOTH USE 

BUFFERS BUILT OF SINGLE UNITS. THE PROCESS CONTROL BLOCKS 

REFER TO A DIFFERENT MH . BUFFER SIZE FOR BOTH APPLICATION 

PROGRAMS IS THE SAME AS THAT FOR THE LINE GROUPS. 



DCB 



DCB 



GROUPONE DCB 



GROUPTWO DCB 



DSORG^TQ , 

MACRF=(G,P ), 

OPTCD=R, 

DDNAME=DISKDD 

DSORG-TQ, 

MACRF=(G,P), 

OPTCD-C, 

DDNAME=CKPTDD 

DSORG=TX, 

MACRF=(G,P), 

CPRI-E, 

DDNAME=DDONE , 

TRANS=1050, 

SCT=1050, 

MH=LINEMH, 

INVLIST=( INVONE), 

PCI-(N,N), 

BUFSIZE=1 16, 

BUFIN=2, 

BUF0UT=4 , 

BUFMAX=4 , 

RESERVE=( 21,0,0,0) 

DSORG=TX, 
MACRF=(G,P), 
CPRI=E, 
TRANS=274F, 
SCT=274F, 
DDNAME=DDTWO , 
MH=LINEMH, 
INVLIST=( INVTWO), 
PCI-(N,N), 
BUFSIZE-1 16, 
BUFIN=2, 
BUF0UT=4 , 
BUFMAX=4 , 
RESERVE=( 21,0,0,0) 



ORGANIZATION IS TCAM DISK 
REQUIRED OPERAND 
DATA SET ON REUSABLE DISK 
NAME OF DD JCL STATEMENT 
CHECKPOINT DATA SET 

DATA SET IS CHECKPOINT 

ORGANIZATION IS TCAM LINE 

SEND/RECEIVE PRIORITY EQUAL 

1050 TRANSLATION TABLE 

SPECIAL CHARACTERS TABLE 

MESSAGE HANDLER FOR LINE 

INVITATION LIST FOR LINE 

NO DYNAMIC BUFFER ALLOCATION 

SIZE OF A BUFFER 

INITIAL ASSIGNMENT - INPUT 

INITIAL ASSIGNMENT - OUTPUT 

MAXIMUM BUFFERS PER LINE 

RESERVED FOR INSERTION OF 

DATA IN MESSAGES 

DCB FOR SECOND LINE GROUP 



FOLDED 2740 TRANSLATION TABLE 



* 

* 
* 

* 
* 
* 

* 

* 



Figure 27. Sample Checkpoint Coordination Program (Part 2 of 1 1) 
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QPROC PCB 



FILE PROCESS CONTROL BLOCK 



RETRV 



PCB FOR RETRIEVE 



MH=APPMH , 
BUFSIZE=1 16, 
BUFIN=5, 
BUF0UT=5 , 
RESERVE=( 5,0 ) 
PCB MH=APPMH , 

BUFSIZE=1 16, 
BUFIN=5, 
BUF0UT=5 , 
RESERVE=( 5,0) 

* 

** TERMINAL AND LINE CONTROL SECTION 

* THIS SECTION DEFINES THE TERMINAL TABLE FOR THE MCP, THE ENTRIES 

* IN THE TERMINAL TABLE, AND THE INVITATION LISTS FOR EACH LINE. 

* IT ALSO DEFINES AN OPTION FIELD TO MAINTAIN A COUNTER OF MESSAGES 

* RECEIVED. THE TERMINALS NYC1 AND NYC2 ARE ASSOCIATED WITH THE 
LINE GROUP DEFINED BY THE GROUPONE DCB, WHILE CHGO IS THE ONLY LINE 
IN THE GROUPTWO LINE GROUP. QUEUING IS BY TERMINAL FOR EACH 
TERMINAL, AND MAIN-STORAGE QUEUING WITH REUSABLE DISK BACKUP IS 
USED. NYC1 AND CHGO ARE BOTH DEFINED AS SECONDARY OPERATOR CONTROL 
TERMINALS. FOUR PROCESS ENTRIES ARE ALSO DEFINED, TWO FOR GET AND 

* TWO FOR PUT PROCESSING. QUEUING FOR THE GET ENTRIES IS MAIN- 

* STORAGE WITH REUSABLE DISK BACKUP. 



COUNTIN 

FILE 



PUTF 
GETR 



PUTR 
NYC1 



* 

NYC2 



CHGO 



TTABLE LAST=CHGO 

OPTION H 

TPROCESS PCB=QPROC, 
CKPTSYN=YES , 
QUEUES=MR, 
ALTDEST=FILE 

TPROCESS PCB=QPROC 

TPROCESS PCB=RETRV, 
QUEUES=MR, 
ALTDEST=GETR 

TPROCESS PCB=RETRV 

TERMINAL QBY=T, 

DCB=GROUPONE , 
RLN=1 , 
TERM=1050, 
QUEUES=MR, 
ADDR=6402, 
NTBLKSZ=( 116), 
OPDATA=0 , 
SECTERM=YES 

TERMINAL QBY=T, 

DCB=GROUPONE , 

RLN=1 

TERM=1050, 

ADDR=6202, 

QUEUES=MR, 

OPDATA=0 , 

NTBLKSZ=( 116) 

TERMINAL QBY=T, 

DCB=GROUPTWO , 
RLN=1 , 
TERM=274F, 
QUEUES=MR, 
ADDR=E201 , 



LAST ENTRY IN THE TABLE 

OPTION FIELD FOR COUNTER 

PCB NAME * 

FOR CHECKPOINTING * 

MAIN-STORAGE, REUSABLE BACKUP * 

ALTERNATE DESTINATION 

SECOND PROCESS ENTRY FOR FILEAP 

PCB NAME * 



SECOND PROCESS ENTRY FOR ARRET 

QUEUING BY TERMINAL * 

ASSOCIATED DCB * 

RELATIVE LINE NUMBER * 

TYPE OF TERMINAL * 

QUEUING TYPE * 

ADDRESSING CHARACTERS * 

SIZE OF A BLOCK * 

INITIAL VALUE OF OPTION * 
SECONDARY OPERATOR CONTROL 
TERMINAL 

SECOND TERMINAL IN GROUP * 

* 

* 

* 

TERMINAL ON OTHER LINE GROUP * 

* 
* 

NONSWITCHED WITH CHECKING * 

* 
* 



Figure 27. Sample Checkpoint Coordination Program (Part 3 of 1 1) 
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NTBLKSZ=( 116), 

OPDATA=0 , 

SECTERM=YES 
INVONE INVLIST ORDER=( NYC1 +640B,NYC2+620B ) GROUPONE INVITATION LIST 
INVTWO INVLIST ORDER=( CHGO+E20 1 , CHGO+E201 ) GROUPTWO INVITATION LIST 

* POLL TWICE BEFORE DELAY 

** MESSAGE HANDLER SECTION 

* THIS SECTION PROVIDES THE MESSAGE HANDLING FUNCTION OF THE MCP . 

* IT CONTAINS TWO MHS . THE FIRST RECEIVES INPUT FROM LINES AND 

* FORWARDS TO THE DESTINATION SPECIFIED IN THE MESSAGE, WHICH MAY BE 
EITHER ANOTHER STATION OR AN APPLICATION PROGRAM. MESSAGES ARE 
COUNTED, AND THE DATA INSERTED DEPENDS UPON A MESSAGE-TYPE 
INDICATOR SPECIFIED IN THE MESSAGE. INVALID MESSAGES ARE 
CANCELED AND MESSAGES INDICATING THE ERROR ARE RETURNED TO THE 
ORIGINATING STATION. THE SECOND MESSAGE HANDLER RECEIVES INPUT 
FROM EITHER OF THE APPLICATION PROGRAMS, SEQUENCES THEM AND 
RETURNS THEM TO THE DESTINATION SPECIFIED IN THE WORK AREA BUILT BY 
THE APPLICATION PROGRAM. 



* 

* 
* 
* 
* 

* 

LINEMH 



STARTMH LC=OUT 

INHDR 

CHECKPT 

COUNTER COUNTIN 

CODE , 

FORWARD DEST=** 

MSGTYPE A 

SEQUENCE 

DATETIME 

MSGTYPE S 

ORIGIN , 

INMSG 

CANCELMG X * 5800000000 ' 



TAKE OUT LINE CONTROL 
PROCESS INCOMING HEADERS 
CHECKPOINT OPTION FIELDS 
COUNT HEADERS RECEIVED 
TRANSLATE TO EBCDIC 
FORWARD TO DESTINATION NAMED 
IN NEXT FIELD OF MESSAGE 
TO AN APPLICATION PROGRAM 
YES - SEQUENCE VERIFY IT 
INSERT DATE AND TIME 
TO A SWITCHED TERMINAL 
YES - VERIFY ORIGIN 
TO PROCESS COMPLETE MESSAGE 
CANCEL MESSAGES WITH INVALID 
ORIGIN OR SEQUENCE NUMBER 
SEND INVALID ORIGIN MESSAGE 
BACK TO WHOEVER SENT IT 
SEND SEQUENCE HIGH MESSAGE 






APPMH 



MSGEN X'4000000000' , 

CL1 8 'ORIGIN FIELD WRONG' 
MSGEN X' 1000000000' , 

CL20' SEQUENCE NUMBER HIGH' TO ITS SOURCE 
MSGEN X ' 0800000000 ' , SEND SEQUENCE LOW MESSAGE * 

CL1 9 'SEQUENCE NUMBER LOW' TO ITS SOURCE 
INEND END OF INCOMING GROUP 

OUTHDR PROCESS OUTGOING HEADERS 

MSGFORM INSERT FOB/EOT AT END 

CODE , CONVERT BACK TO LINE CODE 

OUTEND END OF OUTGOING GROUP OF 

THIS MH 
STARTMH LC=OUT REMOVE LINE CONTROL 

INHDR PROCESS INCOMING HEADERS 

FORWARD DEST=PUT FORWARD TO DESTINATION PROVIDED 

BY APPLICATION PROGRAM 
INEND END OF INCOMING GROUP 

OUTHDR PROCESS OUTGOING HEADERS 

SEQUENCE SEQUENCE OUTGOING MESSAGES 

OUTEND END OF OUTGOING GROUP 



DCBOFLGS EQU X ' 1 ' 
END 



Figure 27. Sample Checkpoint Coordination Program (Part 4 of 1 1) 
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VASMAPP1 JOB MSGLEVEL=1 

V EXEC ASMFC, FARM. ASM='NOLOAD, DECK' 

VASM.SYSIN DD * 

^ILEAP CSECT 

PRINT NOGEN 

** INITIALIZATION SECTION 
* 

* THIS SECTION ESTABLISHES ADDRESSABILITY AFTER SAVING THE CALLER 

* REGISTERS. A QSTART MACRO IS THE FIRST STATEMENT IN THE PROGRAM 

* BECAUSE IT IS NEEDED IN ORDER TO USE THE CKREQ MACRO. 
* 



FOR CKREQ USAGE 
SAVE REGISTERS 
SET BASE REGISTER 
ESTABLISH ADDRESSABILITY 
SAVE ADDRESS OF SAVE AREA 
SET NEW SAVE AREA ADDRESS 



***** 






QSTART 




SAVE (14,12),, 




LR 12,15 




USING FILEAP, 12 




ST 13,SAVE+4 




LA 13, SAVE 


***** 





** ACTIVATION SECTION 
* 

* THIS SECTION OPENS ALL APPLICABLE DATA SETS. IN THIS EXAMPLE, THE 

* ONLY DATA SETS OPENED ARE THE TCAM DCBS . IN A TRUE FILE UPDATING 

* PROGRAM, THE DATA SETS FOR THE FILES WOULD ALSO BE OPENED IN THIS 

* SECTION. 
* 

OPEN DCBIN 
OPEN DCBOUT 

In* 

F** PROCESSING SECTION 
* 

THIS SECTION DOES THE PROCESSING REQUIRED TO UPDATE FILES, AND TAKE 
THE COORDINATED OS AND TCAM CHECKPOINTS. SINCE THIS IS ONLY AN 
EXAMPLE, NO FILES ARE UPDATED. COMMENTS ARE PROVIDED TO EXPLAIN 
WHERE THE UPDATING AND CHECKPOINTING WOULD BE DONE IN A TRUE FILE 
UPDATING PROGRAM. CHECKPOINTS ARE TAKEN AFTER EVERY 5 UPDATES. 



OPEN INPUT DCB 
OPEN OUTPUT DCB 



* 
* 
* 
* 
* 
* 
***** 

LOOP 



LOOP 2 



EQU 

LA 

GET 

LA 

LA 

LA 

EQU 

CLI 

BE 



* 

2,5 

DCBIN, WORK 

5 , GOTMSG 

4,1 

3,WORK+8 

* 

0(3), C'/' 
PUT 



SET A LOOP CONTROL 
GET A TCAM MESSAGE 
GET END OF WORK AREA 
SET LCRECL COUNT 
GET WORK AREA START 

SEARCH FOR END OF DATA 
FOUND - BUILD RESPONSE 



LA 
LA 
CR 
BE 



3,1(3) 
4,1(4)^ 
3,5 
CLOSEM 



BUMP TO NEXT BYTE 
BUMP LRECL COUNTER 
END OF WORK 
YES - ERROR 



Figure 27. Sample Checkpoint Coordination Program (Part 5 of 1 1) 
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B 


LOOP 2 


PUT 


EQU 


* 




LA 


3,1(3) 




MVC 


0( 16,3 ),GOTMSG 




LA 


4,27(4) 




STH 


4,DCBOUT+82 


^ 


PUT 


DCBOUT , WORK 


^ 


BCT 


2 , LOOP 


OSCKPT 


BCR 


0,0 



CKREQ 



GO LOOK AT NEXT BYTE 

GET PAST / 

PUT RECEIVED IN MSG 

INCREMENT LRECL COUNTER 

SET LRECL FIELD 

PUT THE MESSAGE BACK TO THE 

TCAM QUEUES 

DECREMENT A^fD TEST LOOP CONTROL 

THE INSTRUCTIONS NEEDED TO OS 
CHECKPOINT THE FILE JUST 
UPDATED WOULD BE PLACED HERE 
TCAM APPLICATION PROGRAM QUEUE 
CHECKPOINT 

REPLY YES OR NO ' , REP, 1 , WECB 

CLEAR ECB FOR A WAIT 
WAIT FOR RESPONSE 

REPLY YES 

YES - CLOSE DOWN 

CLEAR REPLY AREA 

IK CLEAR WORK AREA TO BLANKS 

GET ANOTHER MESSAGE 

* 

** DEACTIVATION SECTION 
* 

* THIS SECTION DEACTIVATES THE DATA SETS USED BY THE PROGRAM. ANY 

* OTHER DATA SETS OPENED IN THE ACTIVATION SECTION WOULD BE CLOSED 

* IN THIS SECTION. 
* 

CLOSEM 



CTEST 


EQU 


* 




WTOR 


'TIME TO CLOSE 




XC 


WECB (4), WECB 


^ 


WAIT 


ECB=WECB 




CLI 


REP,C'Y' 


^ 


BE 


CLOSEM 




XC 


REP(8),REP 




MVI 


WORK, X' 40' 




MVC 


W0RK+1( 149), wo: 




B 


LOOP 



i 



EQU * 
CLOSE DCBIN 
CLOSE DCBOUT 
L 13, SAVE+4 
RETURN (14,12) 
* 

* 

** ERROR HANDLING SECTION 



CLOSE INPUT DCB 

CLOSE OUTPUT DCB 

RESTORE ADDRESS OF SAVE AREA 

RETURN TO OS SUPERVISOR 



THIS SECTION PROVIDES THE ERROR HANDLING REQUIRED FOR 



* UNCORRECTABLE ERRORS AND THE 
* 



END-OF-DATA SITUATIONS. 



***9iC)i( 






ERROR 


EQU 
WTO 
B 


* 

•SYNAD ENTERED' 
CLOSEM 


END 


EQU 
WTO 
B 


* 

'EODAD ENTERED' 
CTEST 



UNCORRECTABLE ERROR 
CLOSE DOWN THE PROGRAM 



END OF DATA INDICATOR 
TEST IF CLOSEDOWN WANTED 



Figure 27. Sample Checkpoint Coordination Program (Part 6 of 11) 
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4c 

** CHECKPOINT SECTION 
* 

* THIS SECTION PROVIDES THE CHECKPOINTING AS SPECIFIED IN THE 

* EXIT LIST OPERAND OF THE DCB MACROS. 
* 

EXIT 



EQU 
BCR 



0,0 



IF OS CHECKPOINTING WERE 
NEEDED (PER THE EXLST 
OPERAND OF THE DCB MACROS ) 
THIS WOULD BE A ROUTINE TO DO 
THE CHECKPOINTING 
THIS COORDINATES WITH THE 
TCAM CHECKPOINT 



* 

* 
* 

CKREQ 
* 

** DATA SET DEFINITION SECTION 
* 

* THIS SECTION PROVIDES ONLY THE TWO TCAM DCBS . ANY OTHER DCBS 

* RELATIVE TO A FILE TO BE UPDATED WOULD BE DEFINED IN THIS SECTION. 



Hc^H^HcHc 




DCBIN DCB 


DSORG=PS, 




BLKSIZE=124, 




DDNAME=APPLIN, 




SYNAD=ERROR, 




EODAD=END, 




EXLST=EXITLIST, 




LRECL=1 16, 




OPTCD=W, 


\ 


MACRF=GM 


DCBOUT DCB 


DSORG=PS, 




BLKSIZE=124, 




DDNAME^APPLOUT , 




SYNAD^^ERROR, 




EXLST=EXITLIST, 




LRECL=1 16, 




OPTCD=WU, 




MACRF=PM 


***** 




* 




** WORK AREA 


DEFINITION SECTION 


* THIS SECTION DEFINES THE WORK AR 
* 


***** 




SAVE DC 


ISF'O' 


REP DC 


2F'0' 


WECB DC 


F'O' 


WORK DC 


150C' ' 


GOTMSG DC 


C MESSAGE RECEIVED' 


EXITLIST DC 


X'8F' 


DC 


AL3(EXIT) 



PHYSICAL SEQUENTIAL 
SIZE OF MESSAGE AND WORK 
NAME OF DD JCL STATEMENT 
UNCORRECTABLE ERROR HANDLER 
END OF DATA HANDLER 
OS CHECKPOINT EXIT LIST 
SIZE OF LOGICAL RECORD 
BUILD PREFIX FOR SOURCE 
DCB FOR GET 
OUTPUT DCB 



* 
* 
* 
* 
* 
* 
* 
* 

* 
* 
* 
* 
* 
* 
* 



DCB FOR PUT 



USED BY THE PROGRAM. 



SAVE AREA 

REPLY AREA FOR WTOR 

ECB FOR WTOR 

WORK AREA FOR MESSAGE 

MESSAGE PROCESSED INDICATOR 

EXIT FOR CHECKPOINT 

ADDRESS OF CHECKPOINT ROUTINE 



END 



Figure 27. Sample Checkpoint Coordination Program (Part 7 of 1 1) 
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//ASMAPP2 JOB MSGLEVEL=1 

// EXEC ASMFC , FARM . ASM= ' NOLOAD , DECK ' 

//ASM.SYSIN DD * 

RETRIEVE CSECT 

PRINT NOGEN 

* 

** INITIALIZATION SECTION 



* THIS SECTION PROVIDES THE NECESSARY INITIALIZATION FOR THE PROGRAM 

* INCLUDING SAVING OF REGISTERS AND ESTABLISHING ADDRESSABILITY. 

^ )3c ^ ^ ^ 



SAVE 
LR 



( 14,12),,* 

12, 15 
USING RETRIEVE, 12 
ST 
LA 



SAVE REGISTERS 
RESET BASE REGISTER 
ESTABLISH ADDRESSABILITY 
13,SAVE+4 SAVE ADDRESS OF SAVE AREA 

13, SAVE SET NEW SAVE AREA ADDRESS 

* 

** ACTIVATION SECTION 

* THIS SECTION OPENS THE DATA SETS USED IN THE PROGRAM. 



OPEN DCB FOR INPUT 
OPEN DCB FOR OUTPUT 



OPEN DCBIN 
OPEN DCBOUT 

* 

** PROCESSING SECTION 
* 

* THIS SECTION DOES THE PROCESSING NECESSARY TO DETERMINE FROM THE 

* INPUT MESSAGE THE MESSAGE TO BE RETRIEVED, RETRIEVES IT AND SENDS 

* IT BACK TO THE REQUESTER OF THE ORIGINAL MESSAGE. 
* 

L00P1 

GET END OF WORK AREA ADDRESS 
GET REQUESTER MESSAGE 
GET START OF MESSAGE 



LOOP 2 



EQU 


* 


LA 


1 , PTWORK 


GET 


DCBIN, WORK 


LA 


2,WORK+8 


EQU 


* 


CLI 


0(2), C'/' 


BE 


PROCESS 


LA 


2,1(2) 


CR 


2,10 


BE 


CLOSEM 



START OF DATA 

YES - PICK UP RETRIEVE DATA 

BUMP TO NEXT CHARACTER 
END AND NO / 
YES - CLOSE DOWN 



B 



LOOP 2 



CHECK FOR / 



PROCESS 



EQU 

MVC 

MVC 

MVC 

PACK 

XC 

CVB 



TERMWORK( 8 ) , 1 ( 2 ) 
IOWORK( 1 ),9( 2 ) 
DOUBLE( 5 ), 10( 2 ) 
D0UBLE+6( 2 ), DOUBLE ( 5 ; 
DOUBLE (6), DOUBLE 
3 , DOUBLE 



PUT TERMNAME IN POINT WORK 
PUT I OR IN POINT WORK 
PUT SEQUENCE IN WORK AREA 
CONVERT TO PACKED DECIMAL 
CLEAR HIGH-ORDER BYTES 
CONVERT TO HEXADECIMAL 



Figure 27. Sample Checkpoint Coordination Program (Part 8 of 11) 
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//LCDUPDT JOB MSGLEVEL=1 

// EXEC LKED,PARM.LKED- 'LIST, LET, XREF' 

//LKED.SYSLMOD DD DSN-SYS 1 . TCAMLIB , DISP=OLD 



r //LKED.SYSIN DD * 

OBJECT DECK HERE 

NAME UPDTCKPT(R) 
//LKDAPP1 JOB MSGL£:VEL=1 
// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS 1 . TCAMLIB , DISP=OLD 
//LKED.SYSIN DD * 

OBJECT DECK HERE 

NAME FILEAP(R) 
//LKDAPP2 JOB MSGLEVEL=1 
// EXEC LKED 

//LKED.SYSLMOD DD DSN=SYS 1 . TCAMLIB , DISP-OLD 
//LKED.SYSIN DD * 

OBJECT DECK HERE 

NAME RETRIEVE! R) 

//GOUPDT JOB MSGLEVEL=1 ,TYPRUN=HOLD,REGION=120K 

//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

// EXEC, PGM=UPDTCKPT 

//SYSABEND DD SYSOUT=A 

//DISKDD DD DSNAME=SAMP1 ,DISP=SHR 

//CKPTDD DD DSNAME=SAMP2,UNIT=231 1 , V0LUME=SER=TSTAM1 , SPACE=( TRK, ( 3 ) ), 

// DISP=(NEW,CATLG) 

I //DDONE DD UNIT=015 
' //DDTWO DD UNIT=017 

//G0APP1 JOB MSGLEVEL-1 ,TYPRUN=HOLD 

//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

// EXEC PGM=FILEAP 

//APPLIN DD QNAME=FILE 

//APPLOUT DD QNAME-PUTF 

//G0APP2 JOB MSGLEVEL=1 ,TYPRUN=HOLD 

//JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

// EXEC PGM=RETRIEVE 

//APP2IN DD QNAME-GETR 

//APP20UT DD QNAME=PUTR 

Figure 27. Sample Checkpoint Coordination Program (Part 11 of 1 1) 
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.CDUPDT JOB MSGLEVEL=1 

EXEC LKED , FARM . LKED= 'LIST, LET , XREF ' 
.KED.SYSLMOD DD DSN=SYS1 .TCAMLIB,DISP=OLD 
.KED.SYSIN DD * 

OBJECT DECK HERE 

^E UPDTCKPT(R) 
.KDAPP1 JOB MSGLEVEL=1 

EXEC LKED 
:jKED.SYSLMOD dd dsn=sysi .tcamlib,disp=old 

^KED.SYSIN DD * 

OBJECT DECK HERE 

\ME FILEAP(R) 

:kdapp2 job MSGLEVEL=1 

EXEC LKED 
LKED.SYSLMOD DD DSN=SYS1 . TCAMLIB,DISP=OLD 
LiKED.SYSIN DD * 

OBJECT DECK HERE 

PME RETRIEVE! R) 

30UPDT JOB MSGLEVEL=1 ,TYPRUN=HOLD,REGION=120K 

JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

EXEC PGM=UPDTCKPT 
SYSABEND DD SYSOUT=A 
DISKDD DD DSNAME=SAMP1 ,DISP=SHR 

CKPTDD DD DSNAME=SAMP2,UNIT=2311 , V0LUME=SER=TSTAM1 ,SPACE=( TRK, ( 3 ) ) , 
1^ DISP=(NEW,CATLG) 

l!)D0NE DD UNIT=015 
DDTWO DD UNIT=017 

G0APP1 JOB MSGLEVEL=1 ,TYPRUN=HOLD 
JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

EXEC PGM=FILEAP 
APPLIN DD QNAME=FILE 
APPLOUT DD QNAME=PUTF 
G0APP2 JOB MSGLEVEL=1 ,TYPRUN=HOLD 
JOBLIB DD DSN=SYS1 .TCAMLIB,DISP=SHR 

EXEC PGM=RETRIEVE 
'APP2IN DD QNAME=GETR 
'APP20UT DD QNAME=PUTR 



5ure 27. Sample Checkpoint Coordination Program (Part 11 of 1 1) 
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Writing TCAM-Compatible Application Programs 



As described previously, a TCAM message may consist of header and text por- 
tions. The header portion is the primary concern of the Message Handler (MH) 
sections of the Message Control Program (MCP). If any processing of text 
portions of messages is required, it is performed by an application program , 
written by the user to suit the needs of his particular application. The main 
concern of TCAM with respect to an application program is to pass messages to 
the program for processing and later to return the messages to the appropriate 
station. (However, there may be no return message, as in the case of a file update 
application.) TCAM provides the means of transferring data between the parti- 
tions (GET, PUT, READ, WRITE, and CHECK macros), and provides a unique 
scheme for buffer usage for application programs. AppUcation programs run 
asynchronously with the MCP, usually in another partition or region, but always 
as a separate system task or subtask. The MCP must have higher priority than 
any application program, since the MCP must have control after system interrupt 
(this becomes extremely important if the user's application program has a program 
loop that might cause continued contention with the MCP for control). 

TCAM application programs need not be concerned with the station at which a 
message originated, or with the transmission code of the Une, or with what the 
station line control had been. TCAM automatically handles Une control in the 
Message Control Program. However, if a response message is generated, the 
appUcation programmer must consider line-control characters in the response, 
unless a MSGFORM macro is coded in the outheader subgroup handling messages 
for the destination station. The response message must be in line code unless the 
CODE macro is inserted in the outgoing group handUng messages for the destina- 
tion station. 

Messages to be processed are placed in a destination queue by a Message Handler; 
a destination queue and its process entry in the terminal table are defined by a 
TPROCESS macro. A message from a station (or from an application program) 
can be routed to any predefined application program by a FORWARD macro. 

The GET or READ macros that obtain messages from the destination queues 
transfer the data to a user-specified work area. (The work area and the units of 
work placed in it are discussed below.) Once in the work area, the data is ana- 
lyzed and processed by the application program. Optionally, a PUT or a WRITE 
macro causes a response message to be returned to the Message Control Program 
for transmission either to a station (not necessarily the one that originated the 
message), to a list of destinations, or to another application program. 

TCAM application programs allow the user to define at execution time, by the 
QNAME= parameter on the DD card, which of the destination queues specified 
in the terminal table is to be linked to the related data set. 

TCAM allows the user to run his appUcation programs in a non-teleprocessing 
environment for debugging, and then run them under TCAM without reassem- 
bling. The user may include such MCP-related, appUcation-program TCAM 
macros as TCOPY, ICOPY, QCOPY, TCHNG, ICHNG, MRELEASE, and 
MCPCLOSE (aU of which are discussed below) in an application program being 
debugged in a non-teleprocessing environment, provided that the macro definition 
library for the system under which the program is assembled includes the neces- 
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sary macro definitions (as the result of a system generation procedure). When 
these macros are encountered at execution time in a system having no MCP, a 
return code is generated and control passes to the next instruction; otherwise, 
execution of the program is not hindered. 

In some applications, the required processing may be such that one destination 
queue can handle all the messages, and a single apphcation program having a 
single interface with the MCP can perform the processing. If various kinds of 
processing are required, there are two means of providing it: 

• Each of several application programs may be provided with its own interface 
with the MCP, and the destination field in the message header used to route the 
message to the appropriate destination queue for the desired program. 

• Alternatively, all messages that require processing are routed to the same 
application program, where a user-written analysis routine determines the kind 
of message received, based upon a user-specified code-in the message. The 
messages are transferred by this routine to the appropriate processing routines, 
or possibly to a processing program in another partition or region (by a PUT or 
WRITE back to the MCP). 

When the destination field in the header is used to route messages to the appropri- 
ate processing program, the processing needed for the message must be deter- 
mined with Message Handler faciUties. Messages requiring different processing 
can be handled by MSGTYPE or PATH macros (see the descriptions of these 
macros). 

Application programs transfer data to and from the MCP using GET/PUT 
(QSAM) or READ/WRITE/CHECK (BSAM) macro instructions. Support is 
provided for fixed-, variable-, and undefined-format work units. When using 
TCAM's GET/PUT support, the user may specify move or locate mode, but not 
substitute mode. 

If the EODAD= operand is specified in the input DCB macro, the SETEOF 
macro may be issued in the MCP to indicate the end of a file of data, and the 
EODAD exit is taken on the next GET or READ after TCAM moves end-of- 
message into the user's work area. On succeeding GETs or READs, normal 
processing continues. If EODAD is not specified at end-bf-data, the apphcation 
program may stop issuing GETs or READs and issue a CLOSE macro to close the 
input DCB. If no SETEOF macro is issued, the GET or READ with CHECK is 
not finished until a message arrives on the queue. Time of entry to EODAD is 
controlled by the user because of the real-time nature of the process queue for the 
application program. The SYNAD exit for logical errors is handled in the same 
manner as under BSAM and QSAM. The SYNAD AF and SYNADRLS macros 
may be used. 

Certain other features can also be incorporated into an apphcation program: 

• A PUT or WRITE work area prefix can be used to specify the destination to 
which a message can be sent. 

• A GET or READ work area prefix can be used to receive the name of the 
message source. 

• The work area contents may be described to TCAM for PUT or WRITE 
operations and by TCAM for GET or READ operations as first segment, 
intermediate segment, last segment, or single-segment message. 

These three options may be included at execution time by a DD card parameter 
(DCB=OPTCD=operand), or at assembly time by the appropriate DCB oper- 
ands. 
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The POINT macro, used in conjuction with a GET or READ macro, enables the 
user to retrieve a message from a message-queues data set on disk, when this 
message has already been sent to its destination. 

TCAM permits an application program to control a teleprocessing network with 
the TCOPY, ICOPY, COPY, TCHNG, ICHNG, MRELEASE, and MCPCLOSE 
macros. All operator control functions are available from application programs; 
operator commands may be transferred to the MCP by PUT/WRITE macros. 
Responses to operator commands may be directed to any destination queue 
(except a PUT process entry) by the ALTDEST= operand of the PUT process 
entry. 

Application programs written to run with a QTAM Message Control Program can 
be used when conversion is made from QTAM to TCAM. QTAM application 
programs being modified to run under TCAM need only be reassembled with a 
QSTART macro as the first instruction. During execution, the modified appHca- 
tion program operates in most respects as it did under QTAM. Appendix E gives 
details on how to run QTAM application programs under TCAM. 

A TCAM application program is defined as a task containing one or more data 
control blocks opened using data definition statements containing the QNAME= 
parameter. This general definition applies to SAM-compatible and to QTAM- 
compatible application programs prepared to execute in conjunction with a 
TCAM Message Control Program. Therefore, TCAM-related macro instructions 
issued in an application program execute as specified only if the task in which they 
are issued contains an open QNAME data control block. 

One exception to this rule exists. The user may issue a PUT or WRITE from an 
attached task, provided that the task to which it is attached is, by definition, a 
TCAM application program. For example, the attaching task (task A), can open 
the necessary data control blocks required to estabhsh the MCP/application 
program interface and can issue GETs or READs to a process queue. When the 
GET or READ is satisfied, task A analyzes the message and attaches the task 
necessary to process the message. By taking advantage of the exception stated 
above, the attached task can create and PUT or WRITE a response to the mes- 
sage, without a special interface, to return the response to task A for the PUT or 
WRITE. 

Message Flow to an Application Program 

This section describes the flow of a single-segment message between a remote 
station and an application program operating under TCAM with QSAM as the 
SAM interface. The steps described here are repeated for a multisegment mes- 
sage, except that the response message, if any, may be returned by the PUT macro 
any time after the first segment is received. This discussion summarizes message 
flow as discussed in the TCAM Concepts and Facilities, and adds a detail 
unique to application programs, the read-ahead queue. 

A message segment enters the MCP and is placed in a buffer. The segment is 
handled by the incoming group of the MH for the originating station and is placed 
on the destination queue for the application program (called, hereafter, the 
process queue ). 

The segment is then removed from the process queue and handled by the outgoing 
group of the MH for the application program. At this point, the message is 
queued on the read-ahead queue, an area in main storage related to the process 
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queue. The read-ahead queue permits overlap of MCP and application-program 
processing of messages queued for a particular destination. This queue allows a 
message to be removed from a process queue to be processed by the outgoing 
group of the MH for the apphcation program at the same time that a message that 
was previously on a process queue is being processed by the application program 
itself. The application program obtains the message from the read-ahead queue by 
GET or READ macro instructions. These macros obtain the messages in sections 
of data, called work units , that will fit in an area of the application program 
called the work area . The message is placed in the work area for processing; the 
size of the work area bears no necessary relationship to the size of the MCP 
buffers. 

After processing, and assuming there is a response message, the message is 
returned to the MCP, where it is placed in buffers. The buffers are handled by the 
incoming group of the MH for the application program and are placed on the 
appropriate destination queue (which may also be a process queue). After 
handhng by the outgoing group of the MH for the destination, the response 
message is either sent on a line to a remote station or transferred to another 
apphcation program. 

Overview of the MCP/Application-Program Interface 

The TCAM MCP routes messages between an application program and remote 
stations. Because an application program depends on the MCP to perform its 
input/output operations, an interface must be established between an apphcation 
program and the MCP. TCAM allows this interface to be established from an 
apphcation program by: 

• definition of the interface (by the apphcation program input and output DCB 
macros and DD statments, and by the PCB and TPROCESS macros in the 
MCP); 

• initialization and activation of the interface (by the OPEN macro); 

• transfer of messages between the application program and the MCP (by GET, 
PUT, READ, WRITE, CHECK, and POINT macro instructions); 

• deactivation of the interface (by the MCPCLOSE and CLOSE macros). 

TCAM also provides buffer facilities specifically designed for the MCP interface. 

Unlike the functions performed by the analysis and processing routines of an 
application program, these functions are partially or wholly peculiar to TCAM and 
the telecommunications environment. Therefore, TCAM provides routines to 
accomplish these functions. Linkage to these routines is estabhshed by TCAM 
and by standard data management macro instructions in an apphcation program. 

Information necessary for communication between the MCP and an application 
program is provided by a control area defined by a PCB macro issued in the MCP 
(note also that the queues for an apphcation program are defined by a 
TPROCESS macro in the MCP). No more than one application program can use 
a process control block, the control area defined by a PCB macro. 

Message transfer from a destination queue to an application program is controlled 
by an input data control block (input DCB). An input DCB defines a logical data 
set called an input data set, which contains the messages being sent to the apphca- 
tion program from a single destination queue created by a TPROCESS macro. If 
response messages are generated, message transfer from the application program 
to the MH queue is handled by another data control block, the output DCB. An 
output DCB defines a logical data set called an output data set, which contains 



356 OS/MFT and OS/MVT TCAM Programmer's Guide 



u 



( 



messages being returned from the application program to the MCP by one process 
entry in the terminal table. (A PUT, GET, READ, or WRITE macro names a 
DCB. The DCB macro specifies a DD statement. The QNAME parameter of the 
DD statement is coded with the name of a process entry. One data set must be 
defined for each process entry designed to receive messages from and send 
messages to an application program.) The user must define, open, and close the 
logical data sets represented by the DCBs. 

A separate process entry must be specified for each input or output DCB in the 
application program. A DD statement must be provided for each such DCB. The 
format of the DD card is indicated later in this section. 

Figure 28 shows how to set up the interface between the MCP and the apphcation 
program by coding macro operands. Only those operands that help establish the 
interface are shown in the figure. 

The GET, PUT, READ, WRITE, PCB, and input and output DCB macros, and 
the DD statements for the input and output DCB macros, are discussed in detail 
in this chapter. The TPROCESS macro is discussed in the Defining Terminal 
and Line Control Areas chapter. The GET and PUT or READ and WRITE macros 
issued in an application program each specify the name of a data control block 
created by an input or output DCB macro. One input DCB macro must be 
coded in the application program for each terminal-table process entry 
named in a destination field in a message header or in an operand of the 



Name 


Operation 


Operand 
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GET (or READ) 

or 
PUT (or WRITE) dcbname 
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dcbname DCB 
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program 
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Figure 28. Interface between the Application Program and the MCP 
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FORWARD macro to direct messages to the application program. A 
destination queue is created by TCAM for each such process entry. One output 
DCB macro must be coded in the application program for each process entry 
to be associated with response messages entered by the appHcation program. 

Each input or output DCB macro specifies (in its DDNAME= operand) a DD 
statement that must be included as part of the Job Control Language for execu- 
tion of the appUcation program. This DD statement has a QNAME= parameter 
that specifies the name of a process entry in the terminal table of the MCP. The 
TPROCESS macro that creates each process entry has a pcbname operand, which 
names a PCB macro. The PCB macro names an MH to handle messages being 
sent to or received from the application program by process entries whose 
TPROCESS macros name this PCB macro. The PCB macro is similar to the line 
group DCB macro in that both specify Message Handlers and other related values. 
The MH specified by the hne group DCB macro handles messages transmitted 
between remote stations and the computer, while the MH specified by the PCB 
macro handles messages sent to and received from the appHcation program by the 
MCP. 

Defining the Components of the Interface 

Among the components of the MCP/application program interface are: 

• process entries located in the terminal table and referred to by GET/READ 
and PUT/WRITE macros; 

• data control blocks (and DD statements) for the appHcation-program input and 
output data sets; 

• the process control block (this block specifies the MH for the appUcation 
program); 

• buffers to transfer data between the MCP and the appUcation-program work 
areas. 

Process entries are created by TPROCESS macros (described in the chapter 
Defining Terminal and Line Control Areas). The other components of the 
interface are described in this section. 

Defining the Application Program Data Sets and the Process Control Block 

Two types of logical data sets, called the input data set and the output data set, 
must be defined when writing a TCAM application program. 

The input data set consists of the data (messages or records) sent to an application 
program from a single destination queue created by a TPROCESS macro (process 
queue). An input data set is defined by an input DCB macro. One input data set 
should be defined for each process queue. 

The messages or records in an input data set are transferred from the process 
queue to the application program by a GET or READ macro that specifies the 
name of the input data set. 

An output data set contains the messages or records returned from the appUcation 
program to the MCP by a process entry in the terminal table. An output data set 
is defined by an output DCB macro. One output data set must be defined for 
each process entry designed to receive messages from an application program. 
Messages are transferred from the appUcation program to the MCP by a PUT or ^ 

WRITE macro specifying the name of the output data set. w 
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The line group DCB macro for the MCP names the Message Handler that is to 
handle messages sent over any line in the Hne group for which it is issued. For the 
application program, this function is performed by the PCB macro rather than by 
the input or output DCB macro. One and only one PCB macro must be coded for 
each application program that is to interface with the MCP. This macro is coded 
in the MCP rather than in the application program. In addition to assigning an 
MH to the application program, the PCB macro specifies the size of the buffers to 
be assigned by the MCP to handle messages being sent to and received from that 
application program. 

The next sections describe the input and output DCB macros, the DD statements 
required for these macros, and the PCB macro. Many operands of the input and 
output DCB macros are concerned with aspects of data transfer and processing 
(type of record, type of work area, etc.); these operands should not be coded until 
Transferring Data Between an MCP and an Application Program in this 
chapter has been read. 
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dcbname 



keyword operands 



Input DCB Macro 



The input DCB macro 

• defines an input data set for an application program; 

• must be issued for each process queue to which access is gained by the appUca- 
tion program with GET or READ macros; 

• specifies whether BSAM or QSAM is to be used to transfer messages or records 
from the MCP to the application program; 

• specifies the length in bytes of the appUcation-program work area to which data 
is transferred from the MCP; 

• specifies the length in bytes of buffers to be used in the MCP to transfer 
messages from the process queue to the appHcation-program interface; 

• specifies whether the application program is to handle entire messages or 
message portions called logical records; 

• specifies the format and characteristics of records in the input data set; 

• indicates the address of a routine to be given control when the end of a user- 
defined series of data records is reached; 

• indicates the address of a routine to be given control when message overflow 
occurs. 

The input DCB macro allocates main-storage space for a data control block at 
assembly time. Parameters based on the operands specified in the macro are 
included in the data control block. The macro generates no executable code. One 
(and only one) input DCB macro is coded for each process queue to which the 
application program may direct a GET or a READ macro. Only one application 
program and one GET or READ macro may refer to a process queue at any time. 
(The GET or READ specifies the name of the input DCB macro; the DCB macro 
names a DD statement; the DD statement names a process entry in the terminal 
table.) 

The input DCB macro has the following format: 



Name 


Operation 


Operands 


dcbname 


DCB 


keyword operands 



Function: Specifies the name of the macro instruction and also the name of the 

data control block generated by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the operands that can be used. 

Format: May be specified in any order, separated by commas with no intervening 

blanks. 

Notes: The operands are described below. 

When a parameter can be provided by an alternate source, an appropriate symbol 
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DSORG*PS 



MACRF* 



R [P] 



appears below the operand associated with that parameter. When there is no 
alternate source (that is, the parameter must be specified by the operand), no 
symbol is shown. The symbols have the following meanings: 

Symbol Explanation 

DD The value of the operand can be omitted from the DCB macro and 

provided at execution time by the Data Definition (DD) card for the data 
set. 

OE The value of the operand can be provided by the problem program any 
time up to and including the data control block exit at open time. 

PP The value of the operand can be provided by the user's problem program 
any time before open time. 

If DD is specified, OE or PP may also be used. If OE is specified, PP may also be 
used. 

For information on how to provide parameters by means of OE or PP, see Data 
Management Services . The same publication describes the data control block exit 
that can be taken when OE is specified. Information on providing parameters by 
DD is given below in the section DD Statements for the Input and Output 
Data Sets. 



Alternate Source: None. 

Function: Specifies that the data control block governs message transfer to and 

from a destination queue, and identifies the data set organization as physical 

sequential. 

Default: None. This operand is required. 

Format: DSORG=PS 

Notes: This operand achieves TCAM compatibility with QSAM or BSAM. 



Alternate Source: None. 

Function: Specifies the type of access to the destination queue. 

Default: None. This operand is required. 

Format: GM, GMT, GL, GLT, R, RP 

Notes: G indicates GET (QSAM), R indicates READ in move mode (BSAM). 

GET is in move (M) or locate (L) mode. 

The optional T permits the POINT macro to be used in conjunction with GET and 
is required if POINT is to be used with GET. 

The optional P permits the POINT macro to be used in conjunction with READ 
and is required if POINT is to be used with READ. 



If locate mode (L) is specified for a GET, TCAM obtains a work area by the 
GETMAIN macro instruction at OPEN time from the appUcation program main 
storage. TCAM returns the address of the work area in register 1 following the 
first GET macro and uses this work area for succeeding GETs (see Dynamic 
Work' Area Definition in this chapter). Locate mode is inconsistent with BSAM. 



< 
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DDNAIVlE=svmbol 



BLKSIZE=mteger 



BUFL=lnteger 



LRECL=integer 



RECFIV1= 



F 

V[B] 

U 



Alternate Source: PP. 

Function: Specifies the name of the DD statement associated with the data 

control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is omitted, it must be provided by the alternate source. 



Alternate Source: DD. 

Function: Specifies the size in bytes of the application program work area. 

Default: None. This operand is required. 

Format: Unframed decimal integer no smaller than the length of a record as 

specified by the LRECL= operand. 

Maximum: 32760 

Notes: If this operand is omitted, it must be provided by the alternate source. 

The length of optional fields in the work area must be included in the value 
specified for this operand. TCAM uses this field to determine the length of the 
work area. 

For undefined-format work units, the value specified for BLKSIZE= may be 
dynamically overridden on a work-unit-by-work-unit basis by the length operand 
of the READ macro. 



Alternate Source: None. 

Function: Specifies the size in bytes of buffers used in the MCP for messages 

coming to the application program associated with this DCB macro. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 

Notes: If this operand is omitted, the value specified in the BUFSIZE= operand 

of the PCB macro is used. 



Alternate Source: DD. 

Function: Specifies the number of bytes for a record, plus the length of any 

optional fields in the work area. 

Default: If RECFM=F, this operand is required. Otherwise, specification 

optional. 

Format: Unframed decimal integer. 

Maximum: 32760 

Notes: If RECFM=U is specified, the LRECL= field in the input DCB is 

updated after each GET or READ macro with the sum of the number of bytes of 

data fetched by that GET or READ, plus the length of any optional fields in the 

work area. 



Alternate Source: DD. 

Function: Specifies the format and characteristics of the work units in this input 

data set. 

Default: RECFM=U 

Format: F, V, VB, or U. 
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Notes: V specifies that the work units are variable in format. For BSAM and 
QSAM, each work unit is prefaced in the work area by a standard SAM four-byte 
prefix (all entries in the prefix are in hexadecimal format). 

VB specifies that the work units are treated as blocked, although only one work 
unit is transferred per GET or READ. The variable-length work unit work area 
includes a blocked work area prefix of eight bytes if MACRF=R is specified, and 
of four bytes if not. 

U specifies undefined-format work units. TCAM, like SAM, provides no prefix. 
The length of the work unit is stored by TCAM in the LRECL= field in the input 
DCB. TCAM updates the LRECL= field after each GET or READ with the 
length of the work unit. 

F specifies fixed-length work units. The sum of the length of each work unit 
obtained plus the length of any optional fields in the work area is specified by the 
user in the LRECL= field of the input DCB and may be updated before each 
GET or READ. This option should be used only when the number of bytes of 
data in a message is an exact multiple of the number of bytes specified by the 
LRECL= operand. Otherwise, the last portion of the message contains fewer 
bytes than the number specified in the LRECL= operand, and the program would 
have to be capable of handling this smaller portion of the message. 



Alternate Source: DD. 

Function: Specifies the optional fields for the work unit. 

Default: None. Specification optional. 

Format: W, WIJ, WC, WUC, U, UC, C. 

Notes: W specifies that the name of the source of each message is to be placed in 

an eight-byte origin field in the work area. TCAM places the narjie of the source, 

in EBCDIC, in the field, left-adjusted and padded to the right with blanks. If W is 

coded but TCAM cannot determine the message source, the field is filled with 

eight, character blanks. 

U specifies that the work unit to be handled is either a message or a message 
segment that is not a record. If U is omitted, the work unit is assumed to be a 
record. 

C specifies that a one-byte field in the work area, called the position field, is to 
indicate whether the work unit being handled is the first, an intermediate, or the 
last segment of the message and whether a record delimiter has been detected in 
the data. If the application-program user specifies OPTCD=C on his DCB 
macro, a one-byte position field in the work area is used to describe the work unit. 
The control byte is defined as follows: 



< 
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Position Field 

XTl' (1) 

X'40' (blank) 

XT2' (2) 

XT3' (3) 



Work Area Contents 

First portion of message 
Intermediate portion of message 
Last portion of message 
An entire message 



In addition, if the user specified RECFM=U (undefined-length work units) or 
RECFM=V (variable-length work units), and OPTCD=C or CW, the control 
byte may have the following contents: 

Position Field Work Area Contents 

XT5' (5) First portion of message, end-of -record 

XT4' (4) Intermediate portion of message, end-of-record 

XT6' (6) Last portion of message, end-of-record 

XT7' (7) An entire message, end-of-record 

The control byte may have one of the four values above only if the record delimi- 
ter specified on the TPROCESS macro is the last byte of data in the work unit. 



EODAD=address 



SYNAD=address 



EXLST=address 



) 



Alternate Source: PP. 

Function: Specifies the address of an open or closed subroutine to be given 

control after the access method recognizes a user-generated, end-of-file indication 

in the header of a message. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: TCAM takes this exit when the next GET or CHECK macro is issued 

following complete transfer of the end-of-file message into the work area. 



Alternate Source: PP. 

Function: Specifies the address of an open or closed subroutine to be given 

control if message processing is used, the work unit is larger than the work area, 

and OPTCD=C is not specified. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: For more information on the SYNAD exit, see Application Program 

Error Exit in this chapter. 



Alternate Source: PP. 

Function: Specifies the address of the problem-program exit Ust. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The list must start on a fuUword boundary; its format and contents are 

more fully shown in Data Management Services . Each entry is a fuUword made 

up of a control byte followed by the three-byte address of a user- written routine. 

Only two entries in the Ust (those having control bytes of X'05' and X'OF') are 
meaningful for a TCAM input DCB. 

The entry having a control byte of X'05' is the DCB exit entry, it is explained in 
the Data Management Services publication. 
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If the control byte is X*OF', the user-written routine is given control to initiate an 
OS checkpoint of the appUcation program (see the section on coordinating OS and 
TCAM checkpoints in this chapter). 

Upon entry to the routine specified by the exit-list entry, the contents of registers 
and 2 through 13 are the same as they were just before the GET or CHECK 
macro was executed. Register 1 contains the address of this input DCB, while 
register 14 contains the return address for the application program. The user 
routine must save and restore the contents of registers 1 and 14. The contents of 
the user-defined save area must not be altered by the exit routine. 



STOP= (QUICK 
\ FLUSH 
I BOTH 



Function: Specifies type of MCPCLOSE and SYSCLOSE. 

Default: None. Specification optional. 

Format: STOP=QUICK; STOP=FLUSH; STOP:=BOTH. 



QUICK specifies that the EODAD exit of the input DCB macro is to be taken on 
a quick close. FLUSH specifies that the EODAD exit is to be taken on a flush 
close. BOTH specifies that the EODAD exit is to be taken on either type of 
closedown. If the STOP= operand is coded, the EODAD= operand must also be 
coded. 

Note: This operand is for defining the action to be taken if closedown is issued 
while an application program is executing. 
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Output DCB Macro 



The output DCB macro 

• defines an output data set for an application program; 

• must be issued for each process entry set up to receive messages or logical 
records from an application program; 

• specifies whether QSAM or BSAM is to be used to transfer messages or logical 
records from the application program to the MCP; 

• specifies the format and characteristics of records in the data set; 

• specifies the length of the MCP buffers used to receive messages from this 
apphcationpr ogr am ; 

• specifies the address of a routine to be given control when logical output errors 
occur; 

• specifies the address of the problem-program exit list. 

The output DCB macro has the following format: 



Name 


Operation 


Operands 


dcbname 


DCB 


keyword operands 



dcbname 



Function: Specifies the name of the macro instruction and the name of the data 

control block operated on by the expansion of the macro. 

Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



keyword operands 



Function: Specifies the operands that may be used. 

Format: May be specified in any order, separated by blanks with no intervening 

commas. 

Notes: The operands are described below. 

When a parameter can be provided by an alternate source, an appropriate symbol 
appears below the operand associated with that parameter. When there is no 
alternate source (that is, the parameter must be specified by the operand), no 
symbol is shown. The symbols have the following meanings: 



Symbol 



Explanation 



DD The value of the operand can be provided at execution time by the Data 
Definition (DD) card for the data set. 

OE The value of the operand can be provided by the problem program any 
time up to and including the data control block exit at open time. 

PP The value of the operand can be provided by the user's problem program 
any time before open time. 






If DD is specified, OE or PP may also be used. If OE is specified, PP may also be 
used. 
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For information on how to provide parameters by one of these alternate sources, 
see the note following the explanation of DD, OE, and PP in the discussion of the 
input DCB macro. 



DSORG=PS 



DDNAME=symbol 



IV1ACRF= iP^IVI 

[W 



Alternate Source: None. 

Function: Specifies that the data control block governs message transfer to or 

from an application program, and identifies the data set organization as physical 

sequential. 

Default: None. This operand is required. 

Format: DSORG=PS 

Notes: This operand achieves TCAM compatibility with QSAM and BSAM. 



Alternate Source: PP. 

Function: Specifies the name that appears in the DD statement associated with 

the data control block. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If this operand is omitted, it must be specified from the alternate source. 



Alternate Source: None. 

Function: Specifies the method by which messages are to be transferred to the 

destination queue. 

Default: None. This operand is required. 

Format: PM, PL or W. 

Notes: P specifies that messages are to be transferred by PUT macros. W 

specifies that messages are to be transferred by WRITE macros. 



4 



BLKSIZE^integer 



PUT may be in move (M) or locate (L) mode. WRITE imphes move mode. 

If locate mode (L) if specified for PUT, TCAM obtains a work area by the 
GETMAIN macro instruction when the first PUT is executed. TCAM returns the 
address of the work area in register 1 following the first PUT (see Dynamic 
Work Area Definition in this chapter). 



Alternate Source: DD. 

Function: Specifies the size in bytes of the application program work area. 
Default: None. If locate mode is not specified, specification optional. Other- 
wise, this operand is required. 

Format: Unframed decimal integer no smaller than the length of a work unit. 
Maximum: 32760 

Notes: The length of any optional fields in the work area should be included in 
the value specified for this operand. If locate mode is specified by the MACRF= 
operand and this operand is omitted, it must be specified by an alternate source. 



LRECL=lnteger 



Alternate Source: DD. 

Function: Specifies the sum of the number of bytes in the length of a fixed- or 
undefined-length work unit, plus the length of any optional fields in the work area. 
Default: If RECFM=F is specified, this operand is required. Otherwise, specifi- 
cation optional. 



c 
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OPTCD=[W][U][C] 



SYNAD=address 



Format: Unframed decimal integer. 
Maximum: 32760 

Notes: If RECFM=U is specified and no work-unit length is specified by the 
length operand of the WRITE macro, the contents of the field must be updated 
dynamically by the program before a PUT or WRITE macro is issued; user code 
must place the number of bytes of data in the work area (including optional fields) 
into the LRECL= field of the DCB. This may be done with the aid of the DCBD 
macro, described in Supervisor and Data Management Macro Instructions . 

If a value is specified by the length operand of the WRITE macro, this value 
overrides the value specified in the LRECL= field for undefined work units. 



Alternate Source: DD. 

Function: Specifies the type of optional field to l?e used. 

Default: None. Specification optional. 

Format: W, WU, WC, WUC, U, UC, C. 

Notes: W specifies that the program must place the name of the destination of the 

message in an eight-byte destination field in the work area before a PUT or 

WRITE macro is executed. If a FORWARD macro with the operand 

DEST=PUT is coded in the incoming group of the appUcation-program Message 

Handler, the message is routed to the destination specified in this field. 

U specifies that the work unit is a message or a portion of a message that is not a 
record; if U is omitted, the work unit is assumed to be a record. 

C specifies that a one-byte position field in the work area is used to describe the 
position of the work unit in the message of which it is a part. The control byte is 
defined as follows: 



Position 


Field 


Work Area Contents 


X'Fl' 


(1) 


First portion of message 


X'40' 


(blank) 


Intermediate portion of i 


XT2' 


(2) 


Last portion of message 


X'F3' 


(3) 


An entire message 



Alternate Source: PP. 

Function: Specifies the address of a routine to be given control when logical 

output errors occur. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: For more information on this routine, see Application Program Error 

Exit in this chapter. 
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RECFM= 



^ V[B] 



EXLST=address 



Alternate Source: DD. 

Function: Specifies the format of the work units in this output data set. 
Default: RECFM=U 
Format: F, V, VB, or U. 

Notes: V specifies that the work units are variable in length. For BSAM and 
OSAM, each work unit is prefaced in the work area by a standard SAM, variable- 
length record prefix of four bytes (the contents of which are in hexadecimal 
format). The length of the work unit must be provided by setting up the prefix 
before issuing a PUT or WRITE macro. 

If RECFM=VB, the records are treated as blocked, although only one work unit 
is transferred to the MCP per PUT or WRITE macro. The variable-length record 
work area includes a blocked work area prefix of eight bytes if MACRF=W is 
specified, and four bytes if otherwise. 

U specifies undefined-length work units. TCAM, like SAM, provides no prefix. 
The sum of the length of the work unit plus the length of any optional fields in the 
work area must be placed in the LRECL= field of the DCB before each PUT or 
WRITE, unless it is specified by the length operand of the WRITE macro. 

F specifies fixed-length work units. Before the PUT or WRITE, the sum of the 
length of the work unit plus the length of any optional fields in the work area must 
be placed in the LRECL= field of the output DCB. 



Alternate Source: PP. 

Function: Specifies the address of the problem-program exit list. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The description of this operand is the same as that provided above for the 

EXLST= operand of the input DCB macro. 



BUFL=mteger 

Alternate Source: DD. 

Function: Specifies the size in bytes of the MCP buffers that are to receive 

messages coming from this application program. 

Default: None. Specification optional. 

Format: Unframed decimal integer greater than 35. 

Maximum: 65535 

Notes: If this operand is omitted, the value specified in the BUFSIZE= operand 

of the PCB macro in the MCP is the value used. 

DD Statements for the Input and Output Data Sets 

At application-program execution time, one DD statement must be provided for 
each DCB. The DD statement has the following format: 

//ddname DD QNAME=procname 



( 
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ddname 

Is the symbolic name of the DD statement, and must be the same as the name 
specified in the DDNAME= operand of the input or output DCB macro. 

procname 

Is the name of the process entry in the terminal table to which this entry refers. 
This name is assigned by the TPROCESS macro creating the entry. The destina- 
tion queue may be changed at execution time by specifying a different value for 
the QNAME= parameter. 

The following DCB operands may be omitted from the input or output DCB 
macro and coded as parameters of the DD statement when the operand's func- 
tions are to be provided by an alternate source. These operands are explained in 
the discussion of the input and output DCB macros. More than one operand can 
be specified in one DCB= parameter; multiple operands should be separated by 
commas. 

[,DCB=( [BLKSIZE=integer] [ , LRECL=integer ] 
[ ,BUFL=integer] 
[,OPTCD=[W] [U] [C] ] 
[ , RECFM= ( U ) ] )] 

V[B] 

F 
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PCB Macro 



The PCB macro 

• provides a control block in the MCP to interface with an application program; 

• is required for each application program running with the MCP; 

• is coded in the MCP, not the application program. 

The PCB macro generates a named control block, known as a process control 
block (PCB). A process control block provides information needed to communi- 
cate between the MCP and an apphcation program. One and only one PCB 
macro is required for each active application program, although the user may 
assign more than one PCB to a single apphcation program. A PCB may not be 
shared by two active application progranis since a PCB is an inter-task control 
block. 

The PCB macro has the following format: 



pcbname 



Name 


Operation 


Operands 


pcbname 


PCB 


MH=mhname, BUFSIZE=size 
[,BUFIN=Jnumbern[,BUFOUT=Jnumbern 

h s 'if 

[,RESERVE= (integer 1 ,integer2)] 
[,DATE=| YES / ] 
' NO ^ 






Function: Specifies the name of the macro and the name of the process control 
block generated by the macro referred to in the TPROCESS macro. 
Default: None. This name is required. 

Format: Must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ). 



IVIH=mhname 



BUFSIZE=integer 



Function: Specifies the symbolic address of the Message Handler for the applica- 
tion program represented by this macro. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 
identical to the name specified in the name field of a STARTMH macro in the 
Message Handler. 



Function: Specifies the size of the buffers to be assigned to handle messages for 

the associated application program. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than 35. 

Maxim um : 65535 

Notes: This value may be overridden by specifying the BUFL= operand of the 

input or output DCB for the apphcation program. 



I 
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BUFIN=|nuniber> 



BUFOUT= J number) 



Function: Specifies the initial number of buffers requested into which the data in 

the user's PUT/WRITE work area will be emptied. 

Default: BUFIN=2 

Format: Unframed decimal integer greater than 1. 

Maximum: 15 

Notes: The optimum number specifies enough buffers to contain the entire work 

area. 



Function: Specifies the initial number of buffers that may be filled in anticipation of 

a GET or READ. 

Default: BUF0UT=2 

Format: Unframed decimal integer greater than 1 . 

Maximum: 25 

Notes: Used as a read-ahead queue for a process entry. 



RESERVE=(integerl ,mteger2) 



Function: Specifies the number of bytes to be reserved in buffers. 
Default: None. Specification optional. 
Format: Unframed decimal integers. 
Maximum: 255 for each. 

Notes: integerl specifies the number of bytes to be reserved in the buffer receiv- 
ing the first incoming segment of each message entered by an application pro- 
gram; the space is reserved for insertion of data by DATETIME and SEQUENCE 
functional MH macros. 

integerl specifies the number of bytes to be reserved in all buffers, except the first, 
for insertion of characters by the DATETIME macro, integerl is relevant only in 
a multiple- buffer header situation when the DATETIME macro is to insert data in 
a portion of the header that is not in the first buffer (see the description of the 
DATETIME macro for an example of when it might be desirable to execute 
DATETIME on a portion of the header not located in the first segment). 

Data may be inserted in either an incoming or an outgoing message header, but 
space must be reserved in the incoming header. On the outgoing side, reserved 
space is retained for the first buffer only; thus, DATETIME and SEQUENCE 
macros, if specified in an outheader subgroup, operate only on the first segment of 
the message. 

No space need be reserved for data inserted by a MSGEDIT functional MH 
macro. 



) 



The Scan Pointer section of the chapter Designing a Message Handler de- 
scribes how TCAM handles reserve bytes. Each buffer containing header data 
should be large enough to accommodate the segment itself plus any data that may 
be inserted by DATETIME and SEQUENCE macros. If a buffer containing 
header data does not have a sufficient number of bytes reserved in it to accommo- 
date data inserted by a DATETIME or SEQUENCE macro, the macro does not 
execute and control passes to the next instruction in the MH. Unused reserve 
bytes are not sent out with an outgoing message segment when it is sent to its 
destination. 
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DATE= I YES ( 
<NO S 

Function: Specifies whether the date and time of each message received for the 
process entry are to be recorded. 
Default: DATE=NO 
Format: YES or NO. 

Notes: When a message is received for the appUcation program, TCAM records 
the date and time. When the application program issues a GET or a READ 
macro, TCAM places the recorded date/time and the source of the message in the 
area specified by the DTSAREA= operand of the TPDATE macro. 

This operand requires that the DATE= operand also be specified on the 
TPROCESS macro for this process entry. 

Defining Buffers for the Application Program 

Messages being transferred between the appHcation program work area and the 
MCP reside in buffers, as do messages being transferred between the MCP and a 
remote station. The buffers for transferring data to and from the application 
program are ordinary TCAM buffers, described in Defining Buffers, That 
chapter should be read and understood by the programmer responsible for defin- 
ing the application-program buffers, as the structural description and most of the 
design considerations in that chapter can also be used for application-program 
buffers. 

Buffers used to transfer data between an application program and an MCP differ 
from those assigned to a line in two respects: 

• the way in which they are defined; 

• the manner in which they are allocated. / 

The next section describes appUcation-program buffer definition. The following 
section describes the allocation scheme for application-program buffers as part of 
a discussion of appUcation-program buffer design considerations. 

Defining Application-Program Buffers 

A buffer-definition checkUst for the appUcation-program buffers follows. Guide- 
lines for coding many of the operands shown are given in the next section. 

Macro Operand Description of Function and Comments 

INTRO KEYLEN= integer Specifies the bytes in a buffer unit; all buffers in 

the TCAM system are constructed of units of 
this size. (Considerations for coding this oper- 
and are given in the ohz^tQi Defining Buff ers ) 
integer must be between 35 and 255 inclusive. 

PCB BUFSIZE= integer Specifies the size in bytes of the buffers used to 

transfer message segments between the process 
queues for the application program and an 
application-program work area. May be overridden 
for a single input or output data set by the 
BUFL= operands of the input or output DCB 
macro for that data set. integer must be between 
35 and 65535 inclusive. 



i 
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[BUFOUT=dntegern 



h 






[BUFIN=untegern 



Specifies the maximum number of 
application-program buffers that may be 
filled from the destination queue, 
processed by the outgoing group of the 
application-program MH, and placed on the 
read-ahead queue in main storage in anticipation 
of a GET or READ macro, integer must be at 
least 2 (TCAM uses one buffer internally) and 
may be no greater than 25. 

Specifies the initial number of buffers to 

be allocated to receive data being 

transferred by a PUT or WRITE 

macro from the application-program work area 

to the MCP. integer may be between 2 and 15 

inclusive. 



Input [BUFL=integer] Specifies the size in bytes of the buffers 

DCB to be used to transfer message segments 

from the MCP to the 

application program; overrides the value speci- 
fied by the BUFSIZE= operand of the PCB mac- 
ro, integer must be between 35 and 65535 in- 
clusive. 



Output [BUFL=integer] 
DCB 



Specifies the size in bytes of the 
buffers to be used to transfer message segments 
from the appUcation program to the MCP; over- 
rides the value specified by the BUFSIZE= oper- 
and of the PCB macro, integer must be between 
31 and 65535 inclusive. 



Application-Program Buffer Design Considerations 

The user assigns a maximum number of buffers (with the BUFOUT= operand of 
the PCB macro) that can be used at one time to handle messages being transferred 
from MCP process queues to the appHcation-program work area. These buffers 
are used to construct the read-ahead queue . The read-ahead queue is discussed in 
Message Flow to an Application Program in this chapter. TCAM constructs 
one read-ahead queue for each process queue associated with an opened input 
data set. 

The maximum capacity of a read-ahead queue is two messages. Buffers are 
allocated to this queue dynamically, but the queue never contains more than the 
number of buffers needed to handle two messages. If the user specifies (with the 
BUFOUT= operand of the PCB macro) a number of buffers less than that needed 
to contain two entire messages on the read-ahead queue, less main storage is tied 
up by being assigned to the read-ahead queue, but more time is required to 
transfer messages to the application program. 



The following formula for calculating the BUFOUT= operand of the PCB macro 
provides a read-ahead queue always capable of containing two complete mes- 
sages; by specifying a queue of this size, the user minimizes delay in transferring 
messages to the application program. 

I=2X-Hl 
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Here / represents the integer to be coded for BUFOUT=, and X is the maximum 
number of buffers needed to hold one message being transferred to the appUcation 
program. The extra buffer represented by 1 is used internally by TCAM. 

If main-storage-only queuing is the sole type of queuing used for process queues, 
the optimum number of buffers specified by BUFOUT= is reduced; in this case, 
one need specify only enough buffers to handle the largest work unit to be sent to 
the appHcation program for optimal performance of read-ahead queues. 

The BUFIN= operand of the PCB macro specifies the initial number of buffers to 
be allocated to receive data being transferred by a PUT or WRITE macro from 
the application program to the MCP. (If there is more than one appUcation- 
program process entry that may be referred to by PUT or WRITE macros, the 
number of buffers specified by BUFIN= is allocated to each.) Buffers assigned to 
receive data from the application program are deallocated and sent through the 
incoming group of the apphcation-program message handler as they are filled. 

If the number of buffers specified by BUFIN= is not sufficient to handle the 
entire work unit being transferred, TCAM dynamically allocates additional 
buffers. However, such allocation takes time; to optimize performance, a suffi- 
cient number of buffers should be assigned initially to handle the entire work unit. 

The size of the apphcation-program buffers is specified by the BUFSIZE= 
operand of the PCB macro. This size may be overridden for buffers handling data 
being transferred to the application program by the BUFL= operand of the input 
DCB macro, and for buffers handling data being transferred from the application 
program by the BUFL= operand of the output DCB macro. 

Buffer size considerations given in the chapter Defining Buffers are relevant to 
application-program buffers (considerations in that chapter that deal with 
program-controlled interruptions (PCI) are an exception). 

Buffers are sent through the incoming group of the application-program MH as 
soon as they are filled. If a buffer is not filled when the end of the work unit is 
reached, either a time or a space penalty will be incurred, depending upon whether 
a position field is present in the work area, and upon whether message- or record-^ 
processing is specified. (Position fields are discussed in Defining Optional 
Fields in the Work Area in this chapter. Message and record processing are 
described in Specifying Application-Program Work Units .) 

If no position field is present and message processing is specified, the partially 
filled buffer is sent through the incoming group of the application program as soon 
as the last portion of the work unit has been received. In this case a space penalty 
is incurred and main storage is wasted, since the entire buffer is tied up while the 
work unit is being processed by the incoming group. If record processing is 
specified and there is no position field, a buffer that is larger than the work unit it 
contains is not sent through the incoming group immediately, but is held until it is 
filled by a subsequent PUT or WRITE (or until the application-program signals 
end-of-message by closing the output data set); in this case, a time penalty is 
incurred. 

If a position field is present and indicates that the current work unit is the last or 
only work unit in the message, the buffer containing that work unit is sent through 
the incoming group as soon as the work unit is placed in it; if the work unit is 
shorter than the buffer, main-storage space is wasted, as explained above. If the 



c 
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position field indicates that the current work unit is the first or an intermediate 
unit in a multi-unit message, then the buffer is not sent through the incoming 
group until it is filled or until the end of the message is encountered; if the work 
unit is smaller than the buffer, a time penalty is incurred, as explained above. 

When the buffer sizes specified for the origin and the destination of a message are 
different, data movement occurs because prefixes must be added or deleted when 
the message is placed in the buffers for the destination (this is discussed in the 
chapter Defining Buffers ). Because data movement takes time, the buffer size 
for line buffers handling messages being sent to or from an application program 
should be the same as the buffer size for the application-program buffers 
wherever possible. By overriding the buffer size specified by the BUFSIZE= 
operand of the PCB, the BUFL= operand of the input and output DCB macros 
may be used to tailor application-program buffer sizes to buffer sizes for particu- 
lar origin or destination stations. 

For example, if line buffers for all stations that could enter and accept messages 
processed by a particular application program were either 116 bytes or 232 bytes, 
the user could define two input and output data sets (each with its own 
GET/READ and PUT/WRITE process entries), one for each buffer length. He 
could direct all incoming messages for the application program that were entered 
by stations using 1 16-byte buffers to one process queue, and all incoming mes- 
sages for the appHcation program that were entered by stations using 232-byte 
buffers to the other process queue. If he coded BUFSIZE= 1 16 in his PCB macro 
and BUFL=232 in the input DCB macro for the data set containing messages 
placed in 232-byte buffers upon arrival at the computer, no data transfer would be 
necessary when the data was read from the destination queue into application- 
program buffer. 

When transferring responses from the application program, the user would name 
the PUT/ WRITE process entry for the 1 16-byte-buffer output data set or for the 
232-byte-buffer output data set, depending upon the size of the line buffers for 
the destination station. In the output DCB for the 232-byte-buffer output data 
set, he would specify BUFL=232. Again, no data transfer would be necessary 
when messages were read from the destination queues into the line buffers for the 
destination station if this scheme were followed. 

Activating and Deactivating the Application-Program Interface 

Activation and deactivation of the interface between an application program and 
the MCP is handled by OPEN, CLOSE, and MCPCLOSE macro instructions. 
The OPEN and CLOSE macros for TCAM-compatible application programs are 
used and coded in the same way as OPEN and CLOSE macros coded for applica- 
tion programs in a non-teleprocessing environment and are described in the 
Supervisor and Data Management Macro Instructions publication. List and 
execute forms may be coded for OPEN and CLOSE. The user may code options 
for the OPEN and CLOSE macros shown in Supervisor and Data Management 
Macro Instructions to run his application program in a non-teleprocessing envi- 
ronment for debugging purposes; when the program is run in a TCAM environ- 
ment, the option fields are ignored. More than one data set may be opened or 
closed with the same application-program OPEN or CLOSE macros. The OPEN, 
CLOSE, and MCPCLOSE macros are described in this present section. Deactiva- 
tion of the application program is discussed in the chapter Activating and 
Deactivating the Message Control Program . 
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OPEN (application program) 



The OPEN macro for the apphcation program 

• completes initialization and activation of the input and output data sets for the 
application program; 

• is required to activate each data set represented by an input or output DCB 
macro. 

Initialization and activation of the interface to the MCP is accomplished by issuing 
one or more OPEN macros to open the data sets represented by the input and 
output DCB macros. 

One input DCB macro must be coded for each process queue for an application 
program (that is, each queue for which messages can be obtained by GET or 
READ macros). One output DCB macro must be coded for each process entry 
that can be referred to by a PUT or WRITE macro when a work unit is being 
transferred from the apphcation program to the MCP. 

The open routines in TCAM activate the interface between the MCP and the 
apphcation programs. No TCAM macro instructions in the apphcation program 
may be successfully executed before the DCB for the message queues data set has 
been opened in the MCP or after it has been closed (if disk queuing is used), or 
before the input and output data sets are opened or after they are closed. After 
the message queues data sets on disk and application-program data sets have been 
opened, transfer of data to and from the application program can commence. 

The operand field of the OPEN macro consists of one or more postitional ope- 
rands, followed by a single keyword operand. Each positional operand consists of 
the name of the data control block for the data set being opened (the name of the 
block is the name of the DCB macro that created it). A comma is coded between 
names. The optional keyword operand at the end permits the hst and the execute 
form of the macro to be specified. 

The OPEN macro for the application program has the following format: 



symbol 



Name 


Operation 


Operands 


[symbol] 


OPEN 


(dcbname„...)[,MF=(L )] 
\(E,listname)j 



Function: Specifies the name of the macro. 

Default: None. If MF=L is coded, this name is required. Otherwise specifica- 
tion optional. 

Format: Must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ). 

Notes: If MF=L is specified, this name becomes the name of the parameter hst 
generated by this macro. 



i 
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(dcbname„.») 



MF= 



i (EJistname) ) 



Function: Specifies the name of the data control block and is identical to the 

name specified in the symbol field of the DCB macro for the data set being 

opened. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: Register notation may be used, in which case the specified register (2 

through 12) should contain the address of the data control block for the data set 

being opened. The specified register number must be enclosed in parentheses. If 

more than one dcbname is specified, they must be separated by double commas. 



Function: Specifies that a list is to be created, or that a previously created list is 

to be opened. 

Default: None. Specification optional. 

Format: listname must conform to the rules for assembler language symbols. 

Notes: MF=L causes creation of a parameter list based on the OPEN operands. 

No executable code is generated. The user must specify this form of the OPEN 

among his program constants. The parameters in the hst are not used until the 

problem program issues an OPEN (or CLOSE) macro with an MF=(E, listname) 

operand that refers to the list. The name specified in the name field becomes the 

name assigned to the parameter list. 

MF=(E,listname) causes execution of the OPEN routine, using the parameter list 
referred to by listname . This list was created by a macro having the MF=L 
operand specified. Parameters specified in a macro having the MF=(E,listname) 
operand override corresponding parameters in the Hst. 
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CLOSE (application program) 



symbol 



(dcbname,,...) 



The CLOSE macro 

• is issued in the appUcation program to deactivate any open input or output data 
sets. 

CLOSE has the following format: 



Name 


Operation 


Operands 


[symbol] 


CLOSE 


(dcbname,,...) [MF=(l )] 
l(E,listname)j 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the data control block(s) for the data set(s) 

being closed. 

Default: None. This operand is required. 

Format: Framing parentheses must be coded. Each dcbname must conform to 

the rules for assembler language symbols, and must be the same as the name of the 

DCB macro creating the control block. 

Notes: All application-program data sets can be closed with one CLOSE macro 

by including the names of their data control blocks as operands. 

If register notation is used, the register number must be enclosed in parentheses 
and addresses of the data control blocks must previously have been loaded into 
the registers specified. 

If more than one data set is being closed, the names must be separated by double 
commas. 



(IVIF= \ L 



I (E, listname) ) 



Function: Specifies Hst or execute form of the macro. 
Notes: See the OS publication, Supervisor and Data Management Macro 
Instructions^ for the definition and use of this operand. System ABEND 
issues CLOSE macros for all opened DCBs within a task when it abends. 



< 
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MCPCLOSE 



The MCPCLOSE macro 

• initiates closedown of the telecommunications system; 

• is optional in an appUcation program. 

MCPCLOSE may be issued in an application program to initiate system close- 
down. At the time MCPCLOSE is issued in a user-written termination routine, all 
data sets in the application program should be closed (if MCPCLOSE detects an 
open data set in any appUcation program, it issues a WTO message and places the 
MCP in a wait state until all data sets are closed). Following successful execution 
of MCPCLOSE, control passes to a user-specified routine that deactivates the 
MCP. For more information on the use of MCPCLOSE, see Deactivation in the 
chapter Activating and Deactivating the Message Control Program . 

Only one MCPCLOSE macro is needed to close down the entire system. The 
closedown functions of the macro are also available through use of the HALT 
operator command. 

One of the following codes is returned to the application program in register 1 5 
after the MCPCLOSE macro is issued: 



Code Meaning 

X'OOOOOOOO' The MCPCLOSE macro executed successfully. 
X'OOOOOOOC TCAM is not in the system. 
X'00000014' Either 

a) an invalid protection password is specified in the PASSWRD= 
operand, or 

b) the PASSWRD= operand is not specified and is needed 
because the INTRO macro's PASSWRD= operand specifies a 
protection password. 

MCPCLOSE has the following format: 



Name 


Operation 


Operands 


[symbol] 


MCPCLOSE 


4 QUICK )[,PASSWRD=chars] 
(FLUSH j 



symbol 



(quick ) 

^FLUSHj 



\ 



Function: Specifies the name of the macro instruction. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the type of closedown required. 

Default: FLUSH 

Format: QUICK or FLUSH. 

Notes: QUICK specifies that message traffic is to cease upon completion of any 

message currently in progress. Messages queued for the destinations are not 

transmitted. 
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PASSWRD=chars 



FLUSH specifies that input message traffic is to cease upon completion of the 
message currently in progress. All messages queued for the destinations are then 
transmitted. 

Function: Specifies the protection password that enables only qualified applica- 
tion programs to issue the macro. 

Default: None. If the PASSWRD= operand is specified on the INTRO macro in 
the MCP, this operand is required. Otherwise, specification optional. 
Format: One to eight unframed, nonblank characters. 
Notes: If the character string specified in this operand does not match that 
specified in the INTRO macro, the MCPCLOSE macro is ignored and a X*14' 
return code is set in register 15. 

Transferring Data Between an MCP and an Application Program 

TCAM provides the apphcation-program user with facilities for obtaining mes- 
sages from the MCP and for returning response messages to the MCP. 

The TCAM application programmer uses data-transfer macros similar to those of 
the Queued Sequential Access Method (GET and PUT) or the Basic Sequential 
Access Method (READ, WRITE, and CHECK) of OS/360. A TCAM Message 
Control Program performs device-dependent input/output operations for the 
apphcation program. 

Since the macros used by TCAM for transfer of data between an apphcation 
program and an MCP are patterned after those of BSAM and QSAM, the TCAM 
application programmer is expected to be famihar with these access methods, 
which are explained in the Supervisor Services, Data Management Services , and 
Supervisor and Data Management Macro Instructions publications. 

The amount of data transferred from the MCP to an application program by a 
single GET or READ macro, or transferred from an application program to the 
MCP by a single PUT or WRITE macro, is called a work unit . The work unit is 
processed in an appHcation-program work area . A work unit may be an entire 
message, or a portion of a message (which may or may not be a record). A 
message is a unit of data received from or sent to a station and terminated by an 
EOT or ETX line-control character, or, if the CONV= operand of the 
STARTMH macro is coded CONV=YES, by an ETX or EOB line-control 
character. (Line-control characters may be deleted by the MCP, but TCAM 
places the length of each message segment in the buffer prefix for that segment, 
and can determine the message length by adding the contents of the prefix fields.) 

A record is a logical unit of data whose length is defined by operands of the input 
or output DCB macro and delimiting characters in the message. In TCAM, each 
record is transferred to and from a remote station as part of a message, but the 
size of the record need not coincide with the size of the message; one message 
may contain many records. After an incoming message is placed on a process 
queue for the application program, the user obtains the records in it one at a time, 
with one record being passed between the MCP and the apphcation-program for 
each GET or READ macro directed to the process queue. Similarly, a record may 
be sent to the MCP from a work area whenever a PUT or WRITE macro naming 
the work area is issued in the application program. 

Just because a work unit is not an entire message does not mean that it is a record. 
Message processing or record processing is indicated by the OPTCD= operand of 
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the input and output DCB macros. If message processing is specified, but the 
entire message does not fit into the work area, TCAM provides the capabiUty of 
processing a portion of the message in the work area, then bringing in the next 
portion and processing it, until the entire message has been processed. The 
portions of the message processed in this way are not considered to be records, 
since message processing rather than record processing was specified. TCAM 
handles records and other message portions differently, as shown below in the 
discussion of work units and work areas. These differences may be summarized as 
follows: 

• An incoming record cannot overflow the work area, whereas an incoming 
message can. 

• An incoming record may be delimited by a delimiting character specified by the 
RECDEL= operand of the TPROCESS macro; when message processing is 
specified in the input DCB macro, such delimiters are ignored. 

• If neither a delimiting character nor end-of-message is encountered in a record 
by the time the work area is full, the size of the record is assumed to be the size 
of the work area. When message processing is specified, a work-area overflow 
condition is assumed to exist if the work area fills before the entire message is 
read in; in this case, the user specifies, by an input DCB operand, whether he 
wants to process the message piece by piece or go to an error routine. 

• If a delimiting character is specified by the RECDEL= operand of the 
TPROCESS macro named in a PUT or WRITE macro, TCAM places 
the character at the end of each outgoing record. If message processing 
is specified, TCAM places no delimiting character at the end of outgoing 
messages or pieces of messages. 

The next three sections of this chapter discuss in detail the appHcation-program 
work-area, work-unit, and data-transfer macros. 

Defining the Application-Program Work Area 

Work units obtained by a GET or READ macro are transferred from the MCP to 
a work area defined by the user when he codes his application program. The 
work areas for TCAM-compatible application programs are similar to those for 
programs using the Basic or Queued Sequential Access Method. 



Static Work- Area Definition 



A work area may be defined in one of two ways. It may be defined at application- 
program assembly time by a DC or DS assembler instruction issued in the applica- 
tion program. The label of the instruction becomes the name of the work area, 
and is coded in the GET, PUT, READ, or WRITE instructions that move data to 
and from the work area. The size of the work area must be specified in the 
BLKSIZE= operand of the input DCB macro associated with the data set whose 
contents are being transferred to or from the work area. 

When a work area is defined in this way, move processing mode should be speci- 
fied by coding M in the MACRF= operand of the DCB macros referred to by the 
data-transfer macros that use the work area. A static work area may be used to 
receive data from or send data to more than one input or output data set. 



Dynamic Work- Area Definition 



r 



A work area may be defined dynamically at application-program execution time, if 
GET or PUT macros are to gain access to it. If the user specifies locate mode by 
coding L in the MACRF= operand of his input DCB macro, execution of the first 
GET macro referring to the opened data set causes TCAM to dynamically obtain 
a work area (by a GETMAIN macro) in the same area of addressability as the 
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application program, and to move a work unit of data into this work area. The 
length of the work area is that specified by the BUFSIZE= operand of the input 
DCB macro referred to by the GET macro. The address of the work area is 
returned in register 1 , and is saved by TCAM. The second and subsequent 
executions of GET macros referring to the DCB move data into this work area. 

If locate mode is specified by coding L in the MACRF= operand of the output 
DCB macro, execution of the first PUT macro referring to the opened data set 
causes TCAM to dynamically obtain a work area (by a GETMAIN macro) in the 
same area of addressability as the application program. The address of this work 
area is returned in register 1 . This address should be saved by the user and placed 
in work-area-address register before each PUT after the first is issued. The length 
of this work area is specified by the BLKSIZE= operand of the output DCB 
referred to by the PUT macro. The user must move his data into the work area 
before executing another PUT referring to this DCB. Execution of subsequent 
PUT macros referring to this DCB moves the data from this same work area into 
the MCP buffers. 

Moving Data between Input and Output Work Areas 

In some user appHcations, a work unit is transferred from the MCP to the appHca- 
tion program by a GET or READ, processed by the application program, and then 
returned to the MCP by a PUT or WRITE. If move mode is specified in the input 
and output DCB macros for the input and output data sets through which the 
work unit proceeds, then the GET/READ and PUT/WRITE macros may refer to 
the same work area; the user need not move his data from an input to an output 
work area. 

If locate mode is specified in the input or output DCB macro, and move mode is f] 

specified in the DCB macro for the other data set through which the work unit 'i 

passes, then the user can still get by with one work area, because TCAM permits 
specification of a register containing the address of the work area when GET or 
PUT is coded. 

If locate mode is specified for both the input and the output DCB macro, then two 
work areas will be present, and the work unit must be transferred from one to the 
other. 

Defining Optional Fields in the Work Area 

The following operands of the input and output DCB macros cause TCAM to 
create optional fields in the front part of the work area and fill them with data 
(input DCB macro) or to examine these fields (output DCB macro): 

. OPTCD=W 
. OPTCD=C 
. RECFM=V[B] 

If none of these operands are coded, TCAM starts with the first byte of the work 
area when filling or emptying it. 

The contents of the optional fields are not moved out of the work area with the 
message or record being processed. 

Origin and Destination Fields: If W is coded in the OPTCD= operand of the DCB 
macro of the input data set for this work unit, eight bytes of the work area are 
reserved for the name of the source of the message. When the message comes m 

into the work area, TCAM places the EBCDIC name of the source (as specified in ^ 
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the terminal table) into these eight bytes. The name is left-adjusted, and the field 
is padded to the right with blanks if the name is shorter than eight bytes. 

If TCAM cannot determine the origin of a message, the field is filled in with eight, 
character blanks. TCAM usually knows the origin of a message. TCAM does not 
know the origin when a switched station with no ID sequence calls in and fails to 
identify itself by having a valid origin field in the message header checked by an 
ORIGIN macro. If the switched station is assigned an ID sequence that is not 
unique, an incorrect name may be placed in the field. (See the discussion of the 
ORIGIN macro for more information on switched stations with no ID sequences 
or shared ID sequences.) 

The eight-byte origin field immediately precedes the work unit in the work area 
and follows the other two optional fields, if either or both of the other fields are 
present. Figure 29 shows where the origin field goes in the work area. 

If W is coded in the OPTCD= operand of the DCB macro of the output data set 
for this work unit, when a PUT or WRITE macro is issued to move a work unit 
from this work area to the MCP, TCAM looks in an eight-byte field in the work 
area for the name of the destination of the message. The name should be in 
EBCDIC, left- justified, and padded to the right with blanks if necessary. If a 
FORWARD macro with the DEST= operand coded DEST=PUT is executed in 
the inheader subgroup of the Message Handler for an application program, the 
message is sent to the destination specified in the eight-byte field (see the descrip- 
tion of the FORWARD macro). 

TCAM assumes that the eight-byte destination field immediately precedes the 
work unit in the work area (if W is coded in the OPTCD= operand); Figure 29 
shows where TCAM looks for the destination field. Only the work unit, and not 
the contents of the destination field, is transferred to the MCP when a PUT or 
WRITE macro is executed. 

The user with an inquiry-response application may wish to refer to the same work 
area with his GET/READ and PUT/WRITE macros. If he codes W in the 
OPTCD= operands of his input and output DCB macros, TCAM places the origin 
in the eight-byte field when the inquiry message is read into the work area. After 
the application program processes the message data (without changing the con- 
tents of the eight-byte field), a PUT or WRITE macro is issued; the contents of 
the eight-byte field are now assumed to specify the destination. If a FORWARD 
macro with the DEST= operand coded DEST=PUT is coded in the inheader 
subgroup for the application program, the response message will go back to the 
originating terminal. 

Position Field: If C is coded in the OPTCD= operand of an input or output DCB 
macro, a one-byte field is reserved in the work area associated with the DCB (if 
locate mode is specified in the DCB macro) or named by the GET/READ or 
PUT/WRITE macro transferring data to or from an input or output data set. This 
position field is useful when messages sent to the application program are larger 
than the application-program work area that is to receive them (for example, when 
logical records or other message portions, rather than entire messages, are pro- 
cessed by the application programs). 

If C is specified in the OPTCD= operand of the input DCB macro containing the 
work unit to be moved into the work area. TCAM fills in the position field with a 
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code indicating whether this work unit is the first, intermediate, or last portion of 
a message, or an entire message. 

( 
If C is specified in the OPTCD= operand of the output DCB macro for the work 
unit, the application programmer must ensure that the position field contains the 
appropriate code to describe his work unit. TCAM checks this field and uses it to 
account for message portions being transferred to the MCP. The user must not 
interleave segments from different messages. If the operand is omitted from the 
output DCB macro, TCAM must make one of two assumptions, depending upon 
whether record processing or message processing is specified in the OPTCD= 
operand of the output DCB macro (message processing and record processing are 
described in the next section). 

• If message processing is specified, the end of the work unit is assumed to be the 
endof the message — that is, TCAM assumes that one work unit equals one 
message. 

• If record processing is specified, TCAM assumes that all work units being sent 
to the process entry associated with this output DCB, from the time the output 
data set is opened until the time it is closed, are part of the same message — that 
is, the application program signals end-of-message by issuing a CLOSE macro 
after the last work unit in the message is sent to the MCP. 

The position field is located in the work area, immediately to the left of the 
eight-byte origin or destination field. If no origin or destination field is present, 
the position field is located immediately to the left of the first byte of message 
data in the work area. Figure 29 shows the location of the position field in the 
work area. 

SAM Prefix: If V or VB is coded in the RECFM= operand of the input or output ,, 

/I 
DCB macro, a prefix field is assumed to be present in the work area containing the u 

message received from or sent to the data set represented by the DCB. This 

prefix is useful when TCAM/SAM compatibility — the abihty to run application 

programs in a non-teleprocessing environment using SAM data sets, and then run 

the same program in a TCAM environment without reassembUng — is desired (see 

TCAM/SAM Compatibility in this chapter). TCAM requires a SAM prefix when 

variable -format work units are specified in the output DCB macro (such work 

units are discussed in Work-Unit Formats in this chapter). 

The SAM prefix, if present, occupies the first four or eight bytes of the work area, 
as shown in Figure 29. 

If RECFM= V is coded in the input DCB macro, TCAM places a four-byte prefix 
into the work area receiving a work unit from the input data set for which the 
DCB macro was coded. The first two bytes of the prefix contain the binary sum 
of the length of the work unit plus four bytes (the length of the prefix). The 
second two bytes of the prefix each contain binary zeros. 

If RECFM=VB is coded in the input DCB macro, TCAM places an eight-byte 
prefix into the work area receiving a work unit from the input data set for which 
the DCB macro was coded, provided MACRF=R was also coded (a four-byte 
prefix is provided otherwise). The first two bytes of the prefix contain the binary 
sum of the length of the work unit plus eight bytes (the length of the prefix) in 
hexadecimal notation. The second two bytes each contain a binary zero. The 
third two bytes contain a binary number four less than that contained in the first 
two bytes. The final two bytes each contain a binary zero. This eight-byte prefix 
is for BSAM compatibility; work units are treated as if they were blocked records. 
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although only one work unit is transferred for each READ or GET macro execu- 
tion. 

If RECFM=V is coded in the output DCB macro, TCAM assumes that a four- 
byte prefix precedes each work unit being sent to the output data set for which the 
DCB macro is coded. This prefix is similar to a standard SAM variable-length 
prefix; its contents are described above in the discussion of the SAM prefix for the 
input side. It is the application programmer's responsibihty to see that the prefix 
contains the proper data before a PUT or a WRITE is issued. 

If RECFM=VB is coded in the output DCB macro, TCAM assumes that the work 
unit being sent to the output data set for which the DCB macro is coded is preced- 
ed by an eight-byte prefix (provided that MACRF=W is also specified; a four- 
byte prefix is provided otherwise); the layout is the same as that described above 
for the eight-byte BSAM-compatible prefix for the input side. This prefix is for 
BSAM compatibility; work units are treated as if they were blocked, although only 
one work unit is transferred for each WRITE macro. It is the application 
programmer's responsibility to see that the prefix contains the proper data before 
a WRITE macro is executed. 

Specifying Application-Program Work Units 

The way in which TCAM decides how long a work unit is and how to handle it 
depends upon two factors: 

• the format of the work unit (fixed, variable, or undefined); 

• the type of work unit (message or record). 

The user specifies the format and type of work units his application program is to 
process by coding operands of the input and output DCB macros for the applica- 
tion program. These operands indicate whether the work unit is a message or a 
record, and whether it is always the same length or may vary in length from 
message to message or from record to record. 

If messages or records sent to an application program may vary in length, user 
code in the application program will need to be given length of the work unit 
currently being processed. TCAM counts the number of bytes in the incoming 
work unit, adds the number of bytes that must be reserved in the work area for 
optional fields, and places the total either in a special field in the work area or in a 
field in the input DCB (depending upon which field the user specifies in an input 
DCB operand). User code may then inspect this field to determine the length of 
the work unit being processed. 
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Figure 29. Relative Positions of Optional Fields in the Work Area 



Writing TCAM-Compatible Application Programs 387 



Work-Unit Formats 



On the output side of the appUcation program, TCAM must know the length of 
messages or records whose lengths may vary, before these work units can be 
transferred to the MCP. The application programmer must ensure that the sum of 
the work-unit length and the length of any optional fields in the work area has 
been placed in a special field in the work area or output DCB before issuing a 
PUT or WRITE macro to transfer the work unit. 

The next two sections of this chapter discuss the effects of work-unit format and 
type upon the way in which TCAM transfers the work unit to and from the 
application program. Figure 30, at the end of the second section, summarizes 
much of this discussion. 



Work units that always have the same length are said to have a fixed format, while 
work units that may vary in length may have either a variable format or an unde- 
fined format, depending upon the location of the field in which their length is 
stored (for incoming work units) or examined (for outgoing work units) by 
TCAM. 

A fixed-format work unit is one whose length is defined by the number of bytes 
coded in the LRECL= operand of the input and output DCB macros. A 
variable-format work unit is one whose length (plus the length of any optional 
fields in the work area) is stored in the SAM prefix in the work area (see SAM 
Prefix in this chapter). An undefined-format work unit is one whose length (plus 
the length of any optional fields in the work area) is stored in a field in the input 
or output DCB. TCAM counts the number of bytes in the incoming work unit for 
both variable- and undefined-format work units — ^the only difference between the 
two types of work units (other than the lengths of their respective prefixes) is the 
location of the field where the count is stored by TCAM. 

The user specifies the kind of work units his application program expects to accept 
by the RECFM= operand of the input DCB macro. If he codes RECFM=F, then 
TCAM knows that this appHcation program is set up to process fixed-length work 
units and looks for the length of these units in the LRECL field of the input DCB. 
If he codes RECFM=V, then TCAM keeps track of the length of each incoming 
work unit and stores, in the SAM prefix, the sum of this length plus the length of 
any optional fields in the work area If he codes RECFM=U, then TCAM keeps 
track of the length of each incoming work unit and stores the sum of this length 
plus the length of any optional fields in the work area in the LRECL field in the 
input DCB. 

For work units being transferred from an application program to the MCP, a 
similar setup prevails. The user tells TCAM, by the RECFM= operand of the 
output DCB macro, where to look for the length of the work unit being sent back 
to the MCP by each PUT or WRITE macro. If the user specified RECFM=F, 
TCAM looks for the length of the work unit in the LRECL field of the output 
DCB. If the user specifies RECFM=V, TCAM looks for the sum of the length of 
the work unit plus the length of any optional fields in the work area in the length 
field of the SAM prefix in the work area. If the user specifies RECFM=U, 
TCAM looks for the sum of the length of the work unit plus the length of any 
optional fields in the work area in the LRECL field of the output DCB if a PUT or 
WRITE is being issued. It is up to the user to ensure that the field TCAM exam- 
ines contains the correct length; the technique for modifying a DCB field is 
described in Data Management Services . If the WRITE macro is used with the 
length operand, the length specified in the WRITE macro is used. 
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The tables below summarize the TCAM work-unit formats and illustrate how they 
are specified by operands of the input and output DCB macros. 

The delimiter mentioned in the discussions of variable and undefined records is 
the end of the message when message processing is specified; for record process- 
ing, the delimiter may be either the end of the message or a special record- 
dehmiting character specified in by the RECDEL= operand of the TPROCESS 
macro creating the queue used by the GET or READ. 
Work-Unit Formats — Input DCB 



Format 


How Specified 


Significance 


Fixed 
Variable 

Undefined 


RECFM=F 
RECFM=V[B] 

RECFM=U 


All incoming work units (except possibly the 
last in a message) are the same length. When a 
GET or READ macro is executed, TCAM at- 
tempts to bring in the number of bytes specified 
by the LRECL= operand of the input DCB 
macro. 

Incoming work units vary in length. When a 
GET or READ macro is executed, TCAM 
brings in data until a delimiter or the end of the 
work area is encountered, and then places the 
sum of the length of the work unit plus the 
length of any optional fields in the work area in 
the SAM prefix, which precedes the work unit 
in the work area. 

Incoming work units vary in length. When a 
GET or READ macro is executed, TCAM 
brings in data until a delimiter or the end of the 
work area is encountered, and then places in the 
LRECL field in the input DCB the sum of the 
length of the work unit plus the length of any 
optional fields in the work area. 
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Work-Unit Formats — Output DCB 



Format 



How Specified 



Significance 



Fixed 



RECFM=F 



Variable 



RECFM=V[B] 



Undefined 



RECFM=U 



A PUT or WRITE macro referring to this DCB 
moves the number of bytes specified in the 
LRECL field of this DCB from the work area 
to the MCP. TCAM subtracts the length of any 
optional fields from the number specified in the 
LRECL fiield. 

When a PUT or WRITE macro referring to this 
DCB is executed, TCAM determines the length 
of the work unit to be moved by looking in the 
SAM prefix preceding the work unit in the work 
area (and subtracting the length of any optional 
fields in the work area). 

If a PUT macro referring to this DCB is execut- 
ed, TCAM determines the length of the work 
unit to be moved to the MCP by looking in the 
LRECL field of the DCB. If a WRITE macro 
with the 'S' operand referring to this DCB is 
executed, TCAM determines the length of the 
work unit to be moved by looking in the 
LRECL field of the DCB. (In either case, 
TCAM subtracts the length of any optional 
fields in the work area from the value found.) 
If the WRITE macro with the length operand 
referring to this DCB is executed, TCAM uses 
the length specified in the WRITE macro as the 
length of the work unit to be moved. 



Work Unit Types 



An application program may be set up to handle messages or records. A work unit 
may be a message or a portion of a message; a work unit that is a portion of a 
message may be, but need not be, a record. 

The terms message and record are defined above, in the section Transferring 
Data Between an MCP and an Application Program ; differences in the manner 
in which TCAM handles records and the manner in which it handles other mes- 
sage portions that are not records are also summarized under this heading. The 
table at the end of this section gives a more detailed contrast between message 
and record processing by TCAM. 

The user specifies that he has set up his application program to handle messages 
by coding U in the OPTCD= operand of the input DCB macro. If U is not coded, 
TCAM assumes that the incoming work unit is a record. 

Processing the Message as a Work Unit: If U is coded in the OPTCD= operand of 
the input DCB macro, TCAM attempts to read in an entire message when a GET 
or a READ macro is executed. If the work area is large enough to accommodate 
the entire message, TCAM reads in data up to and including the EOT or ETX 
line-control character, unless conversational mode is specified in the STARTMH 
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macro, in which case TCAM reads in a block of data (that is, that amount of data 
deHmited by an EOB or ETB character when received by the computer). If 
LC=OUT is specified in the STARTMH macro associated with the Hne group 
DCB macro, the EOB or ETB line-control character is removed when the message 
comes into the incoming group of the MCP, but the EOT or ETX line-control 
character is not removed. 

If the entire message does not fit into the designated work area, TCAM performs 
one of three actions, depending upon how operands of the input DCB macro are 
coded. 

1. If a position field is specified in the OPTCD= operand, the portion of the 
message that did not fit into the work unit is obtained by the next GET or 
READ macro executed (the position field is discussed in Optional Fields in 
the Work Area in this chapter). 

2. If no position field is specified but SYNAD= is coded, TCAM gives control to 
the routine specified by SYNAD= (this routine is discussed in 
Application-Program Error- Handling Facilities in this chapter). 

3. If neither a position field nor a SYNAD exit is specified, TCAM places a return 
code of X'00000008' in register 15. This return code indicates an error condi- 
tion, and the user should terminate the application program and correct the 
error. 

If TCAM performs the first of these three actions, the application program may 
process the first portion of the message and issue a PUT or WRITE macro to 
return it to the MCP before issuing a GET or READ to bring in the rest of the 
message. 

To determine whether an incoming message fits into the work area, TCAM must 
first know what the length of the work area is. For fixed-format messages, TCAM 
assumes that the length of the work area is equal to the number of bytes specified 
in the LRECL= operand of the input DCB macro. For variable- and undefined- 
format messages, TCAM assumes that the work-area length is equal to the 
number of bytes specified in the BLKSIZE= operand of the input DCB macro. 
When a work-area overflow error occurs, TCAM discards the message that caused 
the overflow. If the input data set is closed and then reopened as a result of 
work-area overflow, the first message received in the work area following reopen- 
ing of the data set is not the message that caused the overflow; this message is 
discarded by TCAM. 

To prevent work-area overflow, the CUTOFF macro can be coded in the inbuffer 
subgroup of the MH; this macro checks the length of incoming messages and 
permits cancellation of messages that would be too long for the work area. 

If U is specified in the OPTCD= operand of the output DCB macro, TCAM 
assumes message processing on the output side. If a position field is specified in 
the work area (by coding OPTCD=C in the output DCB macro), TCAM uses this 
field to determine whether the work area contains an entire message or only a 
portion of a message. If the work area does not contain an entire message, TCAM 
treats each piece of data moved from the work area by a PUT or WRITE as part 
of the same message, until the contents of the position field indicate that the work 
unit currently being processed is the last unit in the message. If no position field is 
specified, TCAM assumes that the entire message is located in the work area. 

Depending upon the format of the work unit (whether it is fixed, variable, or 
undefined), TCAM looks in the SAM prefix or in an output DCB field for the 
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length of the outgoing work unit and sends out the quantity of data specified in 
the appropriate field, after allowing for optional fields in the work area. (See 
Work-Unit Formats in this chapter for information on the exact location of the (; 

field containing the message length.) ^ 

Processing the Record as a Work Unit: If U is not coded in the OPTCD= operand 
of the input DCB macro, TCAM treats the incoming work unit as a record, rather 
than as a message or a message portion that is not a record. 

If the user specifies that the input to his appUcation program is to be fixed-format 
records (by coding RECFM=F in the input DCB macro), TCAM assumes that 
each incoming record is equal in length to the number of bytes specified in the 
LRECL= operand of the input DCB macro (minus the length of any optional 
fields in the work area) and moves in this number of bytes each time that a GET 
or READ macro is executed for this input data set. The last record in a message 
may be shorter than the number of bytes specified by LRECL=, in which case 
TCAM brings in the actual number of bytes in this record. 

If fixed-format records are designated as the output from an application program 
(by coding RECFM=F in the output DCB macro), each time a PUT or WRITE is 
executed TCAM transfers to the MCP a record equal in length to the number of 
bytes specified in the LRECL= operand of the output DCB macro (after making 
allowance for the length of optional fields in the work area). 

If the user specifies that the input to his application program is to be variable- or 

undefined-length records (by coding V or U, respectively, in his input DCB 

macro), TCAM determines the length of incoming records according to the 

following principles: 4 

1. If a delimiting character (specified by the RECDEL= operand of the % 
TPROCESS macro creating the destination queue used by the GET or READ 
macro) is encountered while the work area is being filled, TCAM assumes that 

the current record ends with this character. The user may request that delimit- 
ing characters be removed from the data by specifying DELETE = YES on the 
TPDATE macro. 

2. If the end of a message is reached before the work area is filled, TCAM as- 
sumes that the last character in the message is also the last character in the 
current record. 

3. If neither a delimiter nor the end of the message is reached by the time the 
work area is filled, TCAM assumes that the length of the record is equal to the 
size of the work area (minus the size of any optional fields in the work area). 
TCAM determines the size of the work area by looking in the BLKSIZE field 
of the input DCB. 

When record processing is specified in the DCB macro for the output data set, 
TCAM sends out a single record with each PUT or WRITE. The size of the 
record is indicated in the SAM prefix for variable-format records, in the LRECL 
field of the output DCB, or in the WRITE macro for undefined-format records 
transferred by a PUT or WRITE. 

The following table and Figure 30 summarize many points discussed in this 
section and in the one immediately preceding it. 
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Differences between Message and Record Processing: 



Message Processing 



Record Processing 



On Input: • When GET/READ is issued, 
TCAM brings in data until 
either the end of the 
message is encountered or 
the work area is filled. 



• If the work area has been 
filled and the end of the 
message was not reached, 
TCAM either brings in the 
rest of the message with 
the next GET or READ (if 
a position field is present 
in the work area), or goes to 
the error-handhng routine 
specified by the SYNAD= 
operand of the input DCB 
macro. 

On Output: • Whenever PUT/WRITE is 
executed, TCAM transfers 
one work unit of data from 
the application-program work 
area to the MCP. 



. When GET/READ is 
issued, TCAM brings in 
data until 1 ) the 
delimiting character 
specified by the 
TPROCESS macro referred 
to by the GET or READ 
is encountered, or 2) 
the end of the message 
is encountered, or 3) 
the work area is filled. 
(Delimiting character is 
ignored for fixed-format 
records.) 

• If the work area is 
filled, TCAM assumes 
that a complete record 
has been received. 



• Same as for messages 
— one work unit (record) 
transferred per PUT or 
WRITE. 



• The RECDEL= operand of the 
output TPROCESS macro is 
ignored. 



• The delimiting character 
specified by the RECDEL= 
operand of the output 
TPROCESS is placed at the 
end of each outgoing 
undefined-format record and 
each outgoing variable-format 
record, except for the last 
record of the message. 



I 



• If a position field is pre- 
sent and indicates an initial or 
intermediate segment, TCAM trans- 
fers the rest of the message to 
the MCP when the next PUT or 
WRITE is executed for this out- 
put data set. If no position 



• If a position field 
is present, TCAM con- 
siders all records to be 
part of the same message 
until the position field 
indicates that the cur- 
ent record is the last 
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field is present, TCAM assumes 
that the end of the message coin- 
cides with the end of the work 
area. 



record in the message. 
If no position field is 
present, execution of 
the CLOSE macro for the 
output data set signals 
the end of the message. 



Signaling End of File and End of Message 

TCAM can signal the apphcation program that the contents of the message 
currently being processed by the apphcation program constitute the end of a 
logical file of data; after processing the work unit, or units, in this message, the 
apphcation program may take an exit to a user-defined, end-of-data subroutine. 
Such a subroutine might close the input data set, cause a different type of 
appHcation-program activity to begin, issue a GET or READ macro referring to a 
different process queue, etc. 



The user indicates that the contents of the current message represent the final 
portion of a logical file of data by issuing a SETEOF macro in the outheader 
subgroup of the application-program Message Handler. SETEOF can be coded to 
execute conditionally based on the presence of a specified character string in the 
message header. When SETEOF executes, a bit is set in the prefix of the mes- 
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Figure 30. Effect of Work-Unit Type and Format on the Way in which TCAM Determines its Size 
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sage, indicating that this is the last message in the file. When a message with this 
bit on in the prefix is transferred to the appHcation program by GET or READ 
macros, TCAM notes and remembers that this is the last message in the file. 
Execution of the first GET or CHECK macro following transfer of the entire 
end-of-file message to the application-program work area gives control to the 
subroutine specified by EODAD. 

Upon entry to the user-specified subroutine, the registers contain the same data as 
before execution of the GET or CHECK macro, except that register 15 contains 
the address of the exit subroutine. 

If the user returns from this subroutine to the subroutine issuing GET or READ 
macros, these macros will execute in a normal fashion. 

If no SETEOF macro is executed and a GET or READ macro referring to an 
empty process queue is issued, the application program enters a wait state until a 
message arrives at the process queue for the appUcation program. (If READ was 
issued, the wait state begins only when the CHECK macro is executed.) 

If the SETEOF macro executes and no EODAD exit is specified, when the next 
GET or CHECK macro following transfer of the entire end-of-file message to the 
application program is executed, a completion code of X'00000004' is returned by 
TCAM in register 15, and control returns to the application program. User code 
may check for this return code and take appropriate action. 

If record processing is specified (by the absence of U in the OPTCD= operand of 
the output DCB macro), the user may indicate that this is the last record in a 
message being sent from the application program to the MCP by coding XT2' in 
the position field preceding the record in the work area (see Optional Fields in 
the Work Area in this chapter for a description of the position field). If no 
position field is defined, the program may signal TCAM that the last record in the 
message has been sent by closing the output data set after executing a PUT or 
WRITE macro for this last record. (If message processing is specified, and no 
position field is provided, TCAM assumes that the work unit being processed 
constitutes the entire message.) 

Coding TCAM Data Transfer Macros 

TCAM provides facilities for obtaining messages from the MCP for processing 
and for returning response messages to the MCP. Although the messages are 
received from (or sent to) remote stations over communication Unes, the program- 
mer uses QSAM (GET and PUT) or BSAM (READ, WRITE, and CHECK) 
macros for obtaining and sending messages. A TCAM Message Control Program 
performs the device-dependent input/output operations for the application 
program. The user specifies whether he wishes to use the GET/PUT or 
READ/WRITE/CHECK support in the MACRF= operand of the input and 
output DCB macro. 

Since TCAM GET/PUT and READ/WRITE/CHECK support is similar to that 
provided by OS, the TCAM application programmer is expected to be thoroughly 
familiar with the OS sequential access method (BSAM or QSAM) whose counter- 
part he is coding in the TCAM application program. This requirement implies a 
knowledge of the applicable contents of Data Management Services and 
Supervisor and Data Management Macro Instructions. 
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GET (QSAM only) 



symbol 



dcbname 



The GET macro 

• obtains work units from the MCP for processing; 

• may be coded more than once in an appHcation program. 

The GET macro transfers a single work unit from the MCP to an appHcation- 
program work area. The size of the work unit transferred depends upon whether 
record or message processing is specified by the OPTCD= operand of the input 
DCB macro ( Specifying Application-Program Work Units in this chapter details 
the differences between record and message processing). 

If a GET macro follows a POINT macro and the message cannot be retrieved, a 
code of X'OC is returned in register 15. If a GET macro is issued and the 
BLKSIZE value is zero, a code of X*10' is returned in register 15. 

If a GET macro is issued after a quick closedown of the MCP has begun, the 
EODAD exit is taken. 

GET has the following format: 



Name 


Operation 


Operands 


symbol 


GET 


dcbname[,areaname] 



Function: Specifies the name of the macro instruction. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the symbohc address of the data control block associated 
with the process queue from which the appHcation program is to obtain a work 
unit. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: The DD statement for this DCB names a process entry in the terminal 
table; the process entry is coded especially to receive messages from the appHca- 
tion program. See Overview of the MCP / Application-Program Interface in this 
chapter. 

If register notation is used, the register number (2 through 12) must be enclosed in 
parentheses, and the address of the data control block must previously have been 
loaded into the register. 



Function: Specifies the symboHc address of the user-defined area into which the 
work unit is to be placed. 

Default: None. If move mode is specified in the MACRF= operand of the input 
DCB macro, this operand is required. Otherwise, specification optional. 
Format: Must conform to the rules for assembler language symbols. 



{ 
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Notes: If register notation is used, the specified register number must be enclosed 
in parentheses and the address of the work area must previously have been loaded 
into the register (1 through 12). 

This operand may be omitted if locate mode is specified in the input DCB macro, 
in which case TCAM obtains a work area from application-program main storage 
by issuing a GETMAIN macro instruction when the input data set is opened. 
After the first GET, TCAM returns the address of the work area in register 1. 
TCAM uses this same work area until termination. 
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PUT (QSAM only) 



symbol 



The PUT macro 

• returns work units to the MCP after processing; 

• may be specified more than once in an application program. 

The PUT macro causes the processed message or message segment to be trans- 
ferred from the work area specified to the MCP, where it is processed by the 
incoming group of the MH for the application program, and then placed on the 
destination queue for a particular destination. This destination may be specified 
either in the message header and subsequently checked by a FORWARD macro in 
the incoming group handling messages from an application program, or as an 
operand of the FORWARD macro, or in a special destination field in the work 
area that may be filled in by user code before the PUT is issued (see Defining 
Optional Fields in the Work Area in this chapter for a description of the desti- 
nation field). 

If a PUT is issued and the message queues data set, on reusable disk or in main 
storage, that contains the destination queue for the destination of the message is 
congested with traffic, the PUT does not execute, a code of X'OOOOOOIO' is 
returned in register 15, and control passes to the next instruction; in this case, the 
user may test the return code and re-issue the PUT. 

If a PUT macro is issued after a quick closedown of the MCP has begun the 
operation does not complete, a return code of X'04' is placed in register 15, and 
control passes to the next instruction. If the position field contains an invalid 
value or a value that is out of sequence with the previous position field, a code of 
X'08' is returned in register 15. If the destination name field contains a name that 
is not a valid entry in the terminal name table, X'OC is returned in register 15. 

PUT has the following format: 



Name 


Operation 


Operands 


[symbol] 


PUT 


dcbname[,areaname] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



dcbname 



Function: Specifies the symbolic address of the data control block for the output 
data set. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: The DD statement for this DCB names a process entry in the terminal 
table; the process entry is coded especially to receive messages from the applica- 
tion program. See the Overview of the MCP /Application-Program Interface in 
this chapter. Do not try to execute a PUT or WRITE macro in an application 
program if there is a PUT or WRITE macro currently executing and indirectly 



i 
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I 





referring to (by the TPROCESS entry) the same process control block (PCB). 
This condition could occur if two subtasks of the same apphcation program with a 
single PCB tried to execute a PUT or WRITE macro. If for some reason the 
TCAM MCP must wait before the first operation can be completely processed, 
the second subtask of the same application program could gain control and try to 
execute a PUT or WRITE macro. As a rule, the MCP would be forced to wait 
only if there was a buffer shortage or if the message being processed was an 
operator control message that required a long time to process. 

To guard against this condition, TCAM returns an indication. If an attempt is 
made to execute a PUT macroj TCAM will return an error indication X'lO' in 
register 15. For a WRITE macro, the DECB will contain a completion code of 
X'SCOOOOOO'. Unlike other PUT/WRITE errors, the user is not required to close 
down the DCB affected. 

If more than one subtask in the same apphcation program includes PUT or 
WRITE macros, the possibihty of this type of error can be eliminated by use of 
the ENQ and DEQ macros. ENQ can be coded before each PUT or WRITE, and 
DEQ can be coded after each PUT or WRITE macro. The resource must be a 
name that symbohzes the PCB. See the Supervisor and Data Management 
Macro Instructions publication. 

If register notation is used, the register number specified must be enclosed in 
parentheses, and the address of the data control block must have been loaded 
pi-eviously into a register (1 through 12). 



Function: Specifies the symbohc address of the user-defined work area from 

which the work unit is to be transferred. 

Default: None. If move mode is specified in the MACRF= operand of the 

output DCB macro, this operand is required. Otherwise, specification optional. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the register number specified must be enclosed 

in parentheses and the address of the work area must previously have been loaded 

into a register (0, or 2 through 12). 

If locate mode is used, this operand should be omitted. In this case, the address of 
a work area into which the next work unit is to be placed is returned in register 1 
for the first PUT macro referring to this DCB. For more information on locate 
mode, see Dynamic Work Area Definition in this chapter. 
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READ (BSAM only) 



The READ macro instruction causes a work unit to be moved from the MCP into 
a designated area of main storage in the application program. It differs from the 
GET macro in that control may be returned before the work unit is retrieved when 
READ is used, whereas with GET control is not returned to the application 
program until the work unit is in the work area. The READ input operation may 
be tested for completion using a CHECK macro instruction; once CHECK is 
issued, control is not returned to the appHcation program until the work unit is in 
the work area. 

An appHcation program containing more than one READ macro should be 
designed so that each data event control block (DECB) generated by a READ 
macro is associated with one and only one process queue from OPEN to CLOSE 
(that is, the decbname and dcbname operands of the READ macro, once speci- 
fied, should always be paired; decbname should not be specified with a particular 
dcbname in one READ macro and then associated with a different dcbname in 
another READ macro). The user may specify only one DECB per process queue. 
This technique allows the user to determine the status of any process queue by 
merely interrogating the current completion code in the DECB. See the comple- 
tion codes in the next section. (The DECB is a system control block; for informa- 
tion on the layout of this control block see the System Control Blocks publica- 
tion.) 

If a READ macro is issued after a quick closedown of the MCP has begun, the 
EODAD exit is taken. 

Since only one DECB may be specified per process entry, multiple READ macros 
directed to the same process queue are not permitted. However, the user may 
achieve the effect of issuing multiple READ macros directed to the same process 
queue by coding a hst and an execute form of the READ macro. This is achieved 
by coding one hst form of READ and several associated execute form READ 
macros, where the list READ and all the execute READ macros specify the same 
DECB. This technique does not provide a real multiple- wait facility, but allows 
the application programmer to code READ macros that refer to the same DECB 
in one or more sections of the same program. The list and the execute forms of 
the READ macro are explained in Supervisor and Data Management Macro 
Instructions . 

A DECB is posted with a X'40000000' when a message is placed on a previously 
empty read-ahead queue for a process entry. This implies that a DECB may be 
posted any time during the execution of an appHcation program after the first 
READ macro is issued foHowing OPEN. This differs from BSAM in that a DECB 
becomes eHgible for posting only after a READ macro is issued by the user. 
Therefore, under TCAM/BSAM, a READ DECB may already be posted com- 
plete when the user issues a READ, CHECK, or WAIT macro. 

Example: 

In the following example, two READ macros of the execute form and one READ 
macro of the list form are coded. AH three macros specify the same DECB 
(named INPUT); the Hst READ also specifies the appropriate DCB and work 
area. 



m 
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symbol 



decbname 



SF 



dcbname 



READ 
CHECK 



READ 
CHECK 



LIST 
IN ARE A 
INDCB 



User Code 

INPUT, SF,MF=(E, LIST) 
INPUT 

User Code 

INPUT, SF,MF=( E, LIST ) 
INPUT 

User Code 

Constant Area 

READ INPUT, SF, INDCB, INAREA,MF=L 
DC 50F'0' 

DCB DSORG=PS , MACRF=R, BLKSIZE=200 , 
OPTCD=WUC , RECFM=V , DDNAME=IN 



READ has the following format: 



Name 


Operation 


Operands 


[symbol] 


READ 


decbname,SF, 

dcbname,areaname, 

Uength? 

rs' ilMF^a n 

L KE,Ustname)y 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name to be assigned to the data event control block 

(DECB) created as part of the macro expansion. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



Function: None. Must be coded for proper macro expansion. 
Default: None. This operand is required. 
Format: SF 



Function: Specifies the symbolic address of the data control block associated 

with the process queue being used. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the address of the data control block must 

previously have been loaded into a register (1 through 12), and the register 

number must be enclosed in parentheses. 

The DD statement for this DCB names a process entry, in the terminal table, 
coded especially to receive message from the appUcation program. 
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S length } 



IVIF=fL I 

I (E,nstiiame)| 



Function: Specifies the name of the work area into which the work unit is to be 

placed. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the address of the work area must previously 

have been loaded into a register (2 through 12), and the register number must be 

enclosed in parentheses. 



Function: Specifies the sum of the length of the work unit to be read plus the length 

of any optional fields in the work area. 

Default: *S' 

Format: length is an unframed decimal integer. 

Maximum: 32760 for length. 

Notes: This operand is coded only for undefined-format work units; it is ignored 

for fixed- and variable-format work units. 

Note that S is enclosed in single quotes. If 'S' is coded, and an undefined-format 
work unit is to be processed, the number of bytes to be read is taken from the 
LRECL= operand of the input DCB macro; for undefined-format work units, 'S' 
is the default. 



Function: Specifies the list or execute form of the macro. 

Notes: Described in Supervisor and Data Management Macro Instructions . 



i 
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WRITE (BSAM only) 



symbol 



decbname 



SF 



The WRITE macro 



• returns work units to the MCP after processing; 

• may be specified more than once in an appUcation program. 

The WRITE macro instruction causes the contents of a work area in the applica- 
tion program to be moved to the MCP in the same manner as PUT. Control may 
be returned before the block is moved. The output operation may be tested for 
completion using a CHECK macro instruction. (See the next section for a 
completion code table.) 

The destination may be specified either in the message header and subsequently 
checked by a FORWARD macro in the incoming group handling messages from 
an application program, or by an operand of the FORWARD macro, or in a 
special destination field in the work area that may be filled in by user code before 
the WRITE is issued (see Defining Optional Fields in the Work Area in this 
chapter for a description of the destination field). 

If a WRITE macro is issued after a quick closedown of the MCP has begun, the 
operation does not complete, and a completion code of X'5E' is placed in the 
DECB. 

WRITE has the following format: 



Name 


Operation 


Operands 


[symbol] 


WRITE 


decbname, SF, 
dcbname,areaname, 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name to be assigned to the DECB created as part of the 

macro expansion. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 



Function: None. This operand must be coded for proper macro expansion. 
Default: None. This operand is required. 



dcbname 



^ 
^ 



Function: Specifies the name of the data control block associated with the 

destination queue. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
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{ length I 



Notes: If register notation is used, the specified register number must be enclosed 
in parentlieses and the address of the data control block must previously have 
been loaded into a register (1 through 12). 



Function: Specifies the address of the area from which the work unit will be 

moved to the MCP. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: If register notation is used, the specified register number must be enclosed 

in parentheses and the address of the work area must previously have been loaded 

into a register (2 through 12). 



Function: Specifies the sum of the length of the work unit to be transferred to the 

MCP plus the length of any optional fields in the work area. 

Default: ^ 

Format: length is an unframed decimal integer. 

Maximum: 32760 for length. 

Notes: This operand is meaningful only for undefined-format work units; it is 

ignored for fixed- or variable-format work units. Note that S is enclosed in single 

quotes. If 'S' is specified and and undefined-format work unit is specified, the 

number of bytes to be written is taken from the LRECL= parameter of the output 

DCB macro. 

BSAM/TCAM Completion Codes: After the user has issued a READ or WRITE, 
and the TCAM READ or WRITE routine has completed execution, a completion ,^ 

code is placed in the ECB in the DECB associated with the READ or WRITE. [^ 

The codes are: 

Hex Code Meaning 

7F000000 Normal completion. (READ and WRITE) 

70000000 SETEOF macro executed in MCP. The work area does not contain 

a work unit. (READ only) 
5C000000 Congested destination message queues data set (WRITE only) 
5E000000 TCAM quick closedown has begun. Request rejected. (WRITE 

only) 
58000000 Work unit sequence error. (WRITE only) 
54000000 Invalid message destination. (WRITE only) 
52000000 Work area overflow. (READ only). Also returned if DCB contains 

a BLKSIZE value of zero. 
50000000 READ issued in conjunction with a POINT macro to retrieve a 

message; message not found. 
40000000 Data on read-ahead queue. 
02000000 End of queue condition (not SETEOF and no data in TCAM MCP 

for DCB). 
01000000 Read-ahead queue empty, but destination queue not empty. 

The primary use of these codes is for communication between the READ or 
WRITE and CHECK routines (see the next section). If a user prefers to issue a 
WAIT macro rather than a CHECK macro, he is responsible for testing the 
completion code. A completion code of X'70000000' indicates an end-of-file £ 

condition and requires CHECK to take the user's EODAD exit. Code ^ 
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X'5E000000' indicates that the WRITE was not effective because a request for 
quick close-down is in effect. Code X'5C000()00' indicates that the WRITE was 
not effective because the message queues data set for the destination is congested 
with traffic and cannot accept the work unit at this time. The user may issue 
another WRITE in this case. Codes X^52000000', X^54000000\ and 
X'58000000' indicate error conditions and require CHECK to take the user's 
SYNAD exit. Completion code X'58000000' indicates that the output DCB 
macro associated with the WRITE macro specifies OPTCD=C and that the 
work-unit position field specifies the wrong type of work unit — for example, the 
position field might indicate that this work unit is the first portion of a message, 
but the position field for the previous work unit processed did not indicate that it 
was the last portion of a message. Codes X'02000000' and X'0 1000000' indicate 
that the process queue has no data on it; when data is placed on the queue, the 
code is automatically changed from X'02000000' to X'40000000\ Code 
X'40000000' indicates that after a READ macro was issued and the process queue 
was found to be empty, some data was placed on the process queue. Another 
READ or a CHECK macro should be issued to bring in this data. If SYNAD is 
not specified, a return code of X*00000008' is sent to the appHcation program in 
register 15. 

Neither the wait nor the complete bit in the DECB's ECB is set to 1 by the two 
^'empty-queue" completion codes (X'02000000' and X'0 1000000'). This allows 
the user to wait on ECBs posted in this manner without first having to set the wait 
bit in the ECB to 0. 

User code may test the ECB before issuing a CHECK macro; if the ECB contains 
code X'02000000', the user routine might engage in some other program activity 
rather than issue the CHECK macro and enter a wait state. 
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CHECK (BSAM only) 



The CHECK macro instruction causes the application program to be placed in the 
wait state, if necessary, until the associated input or output operation (READ or 
WRITE) is completed. The input or output operation is then tested for errors. If 
no error occurred, control returns to the instruction following the CHECK macro 
instruction. If an error occurred, the routine specified by the SYNAD= operand 
of the input or output DCB macro is given control. If no error routine is specified 
and an error occurred, a return code of X'08' is sent to the user in register 15 after 
the CHECK macro. 



symbol 



decbname 



A CHECK may be issued after each READ and each WRITE in the same order as 
the READ or WRITE macro instructions are issued. If data is available at READ 
time, it is moved at CHECK time into the work area, and the event control block 
(ECB) in the data event control block (DECB) is posted complete with a return 
code of X'TFOOOOOO' (the ECB is contained within the first four bytes of the 
DECB, on a fullword boundary). If there is no data available and a user- 
controlled end of file has not been generated (by the SETEOF macro), the 
apphcation program CHECK macro waits for data. When data is available, 
CHECK causes data movement; when this has been accomplished, the application 
program receives control after the CHECK macro. 

A WAIT macro may be issued rather than a CHECK by specifying the DECB 
address io the ECB= operand of the WAIT macro; this provides a multiple-wait 
capabiHty (see below). The WAIT macro is described in Supervisor and Data 
Management Macro Instructions . 

CHECK has the following format: 



Name 


Operation 


Operands 


[symbol] 


CHECK 


decbname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the data event control block created by the 

associated READ or WRITE macro instruction. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and must be 

the same as the dcbname for the associated READ macro. 

Notes: If register notation is used, the specified register number must be enclosed 

in parentheses and the address of the DECB must previously have been loaded 

into a general register, 1 through 12. 



If the user detects an empty-queue completion code in the DECB and does not 
wish to wait impHcitly (CHECK) or expHcitly (WAIT), he may do some other 
processing. After this processing, the completion code will have been altered if a 



c 
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message has been placed on the associated read-ahead queue. The user must issue 
either CHECK or another READ to cause the pending READ to complete. This 
technique requires one DECB per process queue. 
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MCOUNT 



The MCOUNT macro 

• returns, in register 1, the number of complete messages on the input queue; 

• can be issued in an appUcation program before a GET or a READ macro to 
determine how many messages are queued for the application program. 

The count returned in register 1 is for the queues associated with the DCB= 
operand of the MCOUNT macro. If the DCB= operand specifies an outgoing 
data control block, register 1 contains a zero. 

The user must issue an OPEN macro for a DCB before issuing an MCOUNT 
macro referring to that DCB. The MCOUNT macro uses standard register 
linkage. Registers 2 through 13 are saved by TCAM. The user must supply the 
address of a save area in register 13. 

One of the following codes is returned to the application program in register 15 
after the MCOUNT macro executes: 



Code 



Meaning 



X'OOOOOOOO' The MCOUNT macro executed successfully 

X'00000004' TCAM is not in the system 

X'00000008' The specified DCB does not define a 

data set for TCAM messages 
X'OOOOOOOC There is no destination QCB for the entry 

MCOUNT has the following format: 



Name 


Operation 


Operand 


[symbol] 


MCOUNT 


DCB = J name; 
<(r) S 



symbol 



DCB= 



iname / 
(r) S 






Function: Specifies the name of the macro. 

Default: None. This name is optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies an input data control block that defines the message queue for 

the application program. 

Default: None. This operand is required. 

Format: name must conform to the rules for assembler language symbols and 

must be the same as the name specified on the DCB macro. 

Notes: If register notation is used, r may be any general register, 2 through 12, 

that has been loaded with the address of the DCB. The specified register number 

must be enclosed in parentheses. 

If the DCB= operand specifies an outgoing data control block, a count of zero is 
put in register 1 . 
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TPDATE 



The TPDATE macro 

• allows the user to specify whether TCAM should delete record delimiters from 
data going to the apphcation program. 

The user must issue an OPEN macro for a DCB before issuing a TPDATE refer- 
ring to that DCB. The TPDATE macro uses standard register linkage. Registers 
2 through 13 are saved by TCAM. The user must supply the address of a save 
area in register 13. 



One of the following return codes is passed to the application program in register 
15 after the TPDATE macro is issued: 

Code Meaning 

X'OOOOOOOO' The TPDATE macro executed successfully. 

X'00000004' TCAM is not in the system. 

X'00000008' The specified DCB does not define a data set for TCAM 

messages. 

TPDATE has the following format: 



Name 


Operation 


Operand 


[symbol] 


TPDATE 


DCB= ( name ( [ ,RECDLM= \ YES ) ] 
j(r) \ <N0 S 

[,DTSAREA= ( area ) ] [,DELETE= K YES \] 
1 (r) f < NO { 



/I 



symbol 



DCB=Jname , 

<(r) 



RECDL!VI=J YES ) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for the assembler language symbols (see the 

entry symbol in the Glossary ). 



Function: Specifies the -data control block that defines the message queue for the 

application program. 

Default: None. Specification required. 

Format: name must conform to the rules for assembler language and must be the 

same as the symbol specified on the DCB macro. If register notation is used r 

may be any general register, 2 through 12, that has been loaded with the address 

of the DCB. The specified register numbers must be enclosed in parentheses. 



Function: Indicates whether the record delimiter specified on the TPROCESS 

macro is to be returned in the low-order byte of register 1. 

Default: NO (this operand is optional) 

Format: YES or NO. 

Notes: If no record delimiter was specified, the value in the low-order byte of 

register 1 will be X*00'. 



{ 
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DTSAREA= { area i 



!(r) 



DELETE= J YES ) 
JNO S 



Multiple-Wait Capability 



Function: Specifies whether the date, time, and origin of a message obtained by 
the appHcation program are to be placed in the 16-byte area specified. 
Default: None. This operand is optional. 

Format: area must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ). If register notation is used, r may be any general 
register 2 through 12. The specified register number must be enclosed in par- 
entheses. 

The format of area is: 





YY 


DD 


DC 


HHMM 


SS 


NN 


C 


C 


c 


c 


c 


c 


c 


c 



where 

YY = last two digits of the year (packed decimal) 

DDD = day of the year (packed decimal) 

C = sign character (for unpacking 

HH = hours (packed decimal) 

MM = minutes (packed decimal) 

SS = seconds (packed decimal) 

NN = hundredths of seconds (packed decimal) 

CCCCCCCC = source (character) 

If the date and time are not available, the date and time fields will contain zeros. 
If the source is not available, the source field will default to blanks. 
Notes: This operand requires that DATE=YES be specified on both the 
TPROCESS and the PCB macros for the application program. 



Function: Specifies whether the record dehmiter is to be deleted from the record 

sent to the appHcation program. 

Default: NO. Specification optional. 

Format: YES or NO. 

Notes: The TPDATE macro must be coded before the GET or READ macros 

when record delimiters are to be deleted from data going to the application 

program or when the date, time, and source are to be provided. 



The user may achieve a multiple-wait capability by issuing more than one READ 
macro to more than one process queue and then issuing a WAIT macro. In the list 
specified by the ECBLIST= operand of the WAIT macro, the user would place 
the addresses of the DECBs associated with the READ macros issued, as well as 
any other DECBs associated with the appUcation program. A message satisfying a 
pending READ macro would cause a completion code of X'40000000' to be 
placed in the associated ECB. After the WAIT macro, one or more CHECK 
macros (or perhaps READ macros) should be coded so that the data will be 
moved into the user's work area. For information on the WAIT macro, see 
Supervisor and Data Management Macro Instructions. 



After the DECB address is made available to the MCP at the time of the first 
READ operation, the MCP posts (with X'40') that DECB when a message or 
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buffer is enqueued on the previously empty read-ahead queue. This impUes that 
the DECB may be posted complete after CHECK, but before the next READ. 
The user should handle this possibility in case of a multiple wait (the DECB is 
always ehgible for posting and should never be waited for unless the user is ready 
to process another work unit). 

Example: 

In the following section of code the user issues READ macros specifying DCBs 
associated with three process queues (DCBA, DCBB, DCBC), and then issues a 
WAIT macro specifying one event and having an ECBLIST= operand pointing to 
a list of addresses of the DECBs associated with the READ macros. When a 
pending READ macro is satisfied, a completion code of X'40000000' is placed in 
the ECB associated with the READ, and the address of the EBC is placed in 
register 1 . If only one event is specified, the user may issue a CHECK macro 
specifying register 1 ; this macro moves the message satisfying the READ into its 
own work area (AREAA if READA was satisfied, AREAB if READB was 
satisfied, AREAC if READC was satisfied). 



READA 


READ 


DECBA , SF , DCBA , AREAA 


READB 


READ 


DECBB , SF , DCBB , AREAB 


READC 


READ 


DECBC , SF , DCBC , AREAC 




WAIT 


1 ,ECBLIST=DECBLIST 




LA 


2, DECBLIST 


LOOP 


L 


1.0( ,2) 




LA 


2,iX{ ,2) 




TM 


0(1), COMP 




BNO 


LOOP 


CHEKIT 


CHECK 

Processing 
Code 


( 1 ) 


DECBLIST 


DS 


OF 




DC 


A( DECBA) 




DC 


A( DECBB ) 




DC 


XL1 '80' 




DC 


AL3( DECBC ) 


AREAA 


DS 


lOOF 


AREAB 


DS 


200F 


AREAC 


DS 


300F 


COMP 


EQU 


X'40' 



END 



Figure 3 1 . Example of Multiple-Wait Capability 



The instruction immediately preceding the last address in the list causes the 
high-order bit of the last entry to be turned on; this is an OS requirement. 

Application Program Error Exits 

The input and output DCB macros for TCAM-compatible application programs 
permit the application programmer to specify an exit to be taken when certain 
errors occur during transfer of data between the MCP and the appHcation pro- 
gram. This is the SYNAD exit, specified in the SYNAD= operand of the DCB 
macro. 



The open or closed, user subroutine whose address is specified in the SYNAD = 
operand receives control when certain errors occur. The user subroutine receives 
input identical to that provided by QSAM and BSAM for their SYNAD exit (as 



( 
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Input to the SYNAD Routine 



explained in Supervisor and Data Management Macro Instructions ). This 
implies that SYNADAF or SYNADRLS macro instructions may be issued in the 
SYNAD routine. The next section details the register contents on entry to the 
SYNAD routine and the contents of the status indicator field for the SYNAD 
routine, while the following section contains information on using the SYNADAF 
macro. 

The SYNAD routine specified by an input DCB macro is given control if 1 ) 
message-type processing has been specified (by coding U in the OPTCD= 
operand), 2) the message to be transferred by the current GET or READ macro is 
larger than that portion of the work area available to it, and 3) no position field is 
specified for this work area (OPTCD= does not specify C). In his SYNAD 
routine, the user must close and reopen this set before issuing another GET or 
READ; otherwise, TCAM will not continue to function properly. The routine is 
entered after a GET or CHECK macro is issued. If the error condition occurs and 
SYNAD is not specified, TCAM returns a completion code of X^OOOOOOOH' in 
register 15 following GET or CHECK. In this case, user code should close the 
data set. 

The SYNAD routine specified by an output DCB macro is given control when one 
of two logical output errors occur: 

1. The position field contains a value that is invalid (not X'40\ X'FT, XT2\ or 
XT3') or that indicates that the current position of the message is out of 
sequence (for example, the position field indicates that this is the first portion 
of the message, but the position field for the previous work unit did not indicate 
end-of-message). 

2. The destination name in the destination field is not a valid entry in the terminal 
table. 

For BSAM, this exit is entered only from the CHECK routine. If SYNAD= is not 
specified, condition (1) above results in a completion code of X'00000008' in 
register 15, while condition (2) results in a code of X'OOOOOOOC. 



Input to SYNAD from TCAM/SAM access method modules is compatible with 
SAM. Register contents on entry to the SYNAD routine are as follows: 

Register Bits Meaning 

8-31 Address of the data event control block (DECB) for BSAM; 

address of status indicators for QSAM. 
Bit is on for error caused by GET or READ. 
Bit is on for error caused by PUT or WRITE. 
Bit is on if user specified an invahd destination (PUT or WRITE). 
Address of associated data control block (DCB). 
Contents before the macro instruction was issued. 

Return address. 

Address of error analysis routine specified by the SYNAD= 

operand of the input DCB. 

Word five (5) of the DECB (DECB+16) contains the status indicator address for 
BSAM support. Status indicators for the SYNAD routine are as follows: 



1 







1 




4 




8-31 


2-13 


8-31 


14 


8-31 


15 


8-31 
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SYNADAF 



Offset from status 
Indicator address 


Meaning 


Byte 


Bit 


Command reject (work units out of sequence). 
Incorrect length (work area overflow). 


+2 
+ 13 


a 

1 



All other fields in the SAM-compatible status indicator field are unused by 
TCAM. Main storage for this block is allocated at OPEN time if the SYNAD= 
keyword is coded in the DCB macro instruction or if provision is made by an 
alternate source. 



If the user issues a SYNADAF macro specifying BSAM or QSAM in his error 
analysis routine, he receives the following values in the specified registers: 

Register 1 contains the address of a buffer containing a message describing the 
TCAM/SAM error. The message consists of EBCDIC information and is in 
the form of a variable length record (see table below). 

Register contains a return code of X'OO', right-adjusted. 

See Supervisor and Data Management Macro Instructions , for further informa- 
tion on the use of SYNADAF and SYNADRLS. 



Format of TCAM/SAM SYNADAF Message Buffer 



Bytes 


Contents 


0-7 


SAM variable (or variable blocked) length prefix 


8-49 


(character blanks) 


50-57 


job name 


58 


, (character comma) 


59-66 


stepname 


67 


, (character comma) 


68-73 


(character blanks) 


74 


, (character comma) 


75-82 


ddname (name of DD statement in which QNAME= 




parameter is coded) 


83 


, (character comma) 


84-89 


macro format (GET, PUT, READ, or WRITE) 


90 


, (character comma) 


91-105 


error description (WORKAREA OFLOW, INVALID DEST, or 




SEQUENCE ERROR) 


106 


, (character comma) 


107-120 


**************** 


121 


, (character comma) 


122-125 


TCAM 



{ 
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Network Control Facilities 

TCAM provides facilities for dynamically controlling the telecommunications 
network through macro instructions issued in an application program. Three 
macros are provided to allow the contents of a control block to be examined: 
TCOPY, ICOPY, and QCOPY. Two macros are provided to allow modification 
of the contents of a control block: TCHNG and ICHNG. TCAM also provides 
the MRELEASE macro, which releases messages queued for an intercepted 
station, and the MCPCLOSE macro (discussed in Activation and Deactivation 
of the MCP Interface in this chapter), which initiates closedown of the Message 
Control Program. These macros are described in detail below. The facilities 
provided by these macros are also available using the operator commands of the 
operator control facihty (see each macro description below). 

In order to execute, TCOPY, QCOPY, and TCHNG require at least one open 
input or output DCB for this apphcation program task. 

Application-Program Network-Control Macros 



Interrogation 


Capability 


• TCOPY 


Copy the contents of a designated terminal table entry and its 




associated option fields into a work area. 


. ICOPY 


Copy the contents of a specified line's invitation list into a 




work area. 


• QCOPY 


Copy the contents of the queue control block (and its related 




priority QCBs) associated with a terminal (or process entry) 




into a work area. 



Modification Capability (Password Protection Optional) 



INTRO 



TCHNG 



ICHNG 



MRELEASE 
MCPCLOSE 



PASSWRD= \ chars 



\ chars / 



Defines the password. 



Place contents of work area into a terminal table entry and its 

associated option fields. 

Replace a specified invitation Hst with the contents of the 

work area, or activate or deactivate all entries in the specified 

list. 

Activate a destination for receipt of messages from the CPU. 

Initiate termination of the TCAM message control program. 



In addition to these macros, TCAM provides the user with the capabiHty of 
defining his application program as a secondary operator control station (by 
coding the SECTERM= operand of the TPROCESS macro) and of entering 
operator commands from it by means of PUT or WRITE macros. Responses to 
these commands are sent to the destination specified by the ALTDEST= operand 
of the TPROCESS macro creating the terminal table, process entry associated 
with the PUT or WRITE macro. For more information on the use of an applica- 
tion program as an operator control station, see Entering Operator Commands 
from an Application Program in the chapter Using TCAM Service Facilities. 






Protection against unauthorized use of the ICHNG, TCHNG, MRELEASE, and 
MCPCLOSE macros is provided by the PASSWRD= operand of these macros. 
The password specified must be the same as the password specified by the 
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PASSWRD= operand of the INTRO macro, otherwise, the application program 
macro is ignored. 

The user might code a special application program designed solely to modify the 
teleprocessing system in the event of errors or other unusual conditions. For 
example, he might code ERRORMSG or REDIRECT macros in an inmessage 
subgroup handhng messages coming in over a hne group. These macros could test 
various bits in the message error record, and when these bits were on, the macros 
could direct a special error message, or the message being handled when the error 
occurred, to the process queue for the appHcation program. The application 
program could fetch error messages by GET or READ macros, analyze them, and 
issue operator commands (if it were designated a secondary operator control 
station by the TPROCESS macro) or network-control macros to modify the 
system in a manner appropriate to the error detected. 

The user is required to have at least one open TCAM DCB in the application 
program task in which these network-control macros are issued. To insure 
reliability, the statname operand of the TCOPY and MRELEASE macros arid the 
termname operand of the TCHNG and QCOPY macros should not exceed the 
value coded in the MAXLEN= operand of the TTABLE macro. Since the user is 
not required to place the name in an eight-byte field, left-adjusted and padded 
with blanks, TCAM cannot check the validity of a name with respect to length. 
This may result in finding a match in the termname table that exceeds the 
maximum termname length in the MCP. 



( 
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TCOPY 



The TCOPY macro 

• permits examination of the contents of a terminal table entry and its associated 
option fields; 

• is optional in a TCAM appHcation program. 

TCOPY moves the contents of a designated terminal table entry to a work area, 
together with the contents of any option fields that are associated with the entry. 
The terminal table entry may be any of the entry types. 

Various functions of TCOPY are also provided by the STSTATUS and 
OPTFIELD operator commands (see the Operator Commands section in Using 
TCAM Service Facilities), Execution of TCOPY alters the contents of registers 
Hand 15. 

The dummy section (DSECT) describing the single, line, and group, terminal table 
entries has the following format: 



The length of the TRMOPT field is variable. If no OPTION macros are coded in 
the MCP, no space is allocated for the TRMOPNO field, the TRMOPTBL field, 
or the TRMOPT field. A variable number of device-characteristics fields follow 
the TRMOPT field (if OPTION macros are coded) or the TRMCHCIN field (if 
no OPTION macros are coded). The first byte of each device-characteristics field 
contains the binary length of the rest of the field; the rest of the field contains the 
device-dependent data. 

In addition to the contents of the terminal table entry itself, TCOPY moves the 
contents of any option fields associated with a terminal table entry into the 



TRMSTATE 


TRMDESTQ 



+1 



■^H 



TRMINSEQ 



TRMOUTSQ 






+4 



+6 



TRMALTD 



TRMDEVFL 



iH 

^h 

TRMTEMPRi TRMSENSE 

IH 

^h 



+8 



+10 



TRMSIO 



+12 



+14 



TRMCHCIN 



TRMOPNO 



TRMOPTBL 



iH 



+16 



+17 



+18 



TRMOPT 



Start of device 
characteristics field 



+20 

Figure 32. Terminal Table DSECT for Single, Line, and Group Entries 
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specified work area. The first option field immediately follows the last device- 
characteristics field in the work area. A two-byte field named TRMOPTBL, 
located at an offset of 18 bytes from the beginning of the terminal table entry, 
contains the offset from the beginning of the terminal table entry to the beginning 
of the first option field in the user's work area. 

The user must ensure that his work area is large enough to accommodate the 
largest possible string of data moved into it by TCOPY. (If the work area is not 
large enough to accommodate the data, the contents of main storage adjoining the 
work area are overlaid and lost.) The user may determine the length of the longest 
possible string of data that the TCOPY macro can move into his work area by 
looking at the assembly listing for his MCP. Under each TERMINAL, TLIST, 
TPROCESS, and LOGTYPE macro expansion are control sections having 
TERMINAL ENTRY, OPTION OFFSETS, and DEVICE-DEPENDENT FIELDS in their 
comment fields. These CSECTs indicate the length of the terminal table entry, 
the option-field offsets, and the device-characteristics fields, respectively. The 
user should find the sum of these lengths for each terminal table entry he might 
wish to copy using TCOPY, and add to this sum the total length of the option 
fields associated with that entry. The work area named in TCOPY should contain 
a number of bytes equal to or greater than the largest sum obtained in this way. 



One of the following return codes is returned to the apphcation program in 
register 15 after the TCOPY macro is issued: 



Code 

X'OOOOOOOO' 
X*00000008' 
X'OOOOOOOC 



X'00000020' 



Meaning 

The TCOPY macro executed successfully. 

TCAM is not in the system. 

A TCAM apphcation-program DCB is not open; at least one 

input or output DCB must be open in order for this macro to 

execute. 

An invahd station name is specified in the field of the TCOPY 

macro (that is, no such entry exists in the terminal table). 



c 



symbol 



For a complete description of terminal table entries, see the discussion in section 
5, Data Area Layouts , in the TCAM PLM . 

TCOPY has the following format: 



Name 


Operation 


Operands 


[symbol] 


TCOPY 


statname, areaname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



statname 



Function: Specifies the name of the station whose contents are to be moved to 

the work area. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be the 

same as the name for the station specified in the MCP terminal table. 



c 
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Notes: If register notation is used, the register must previously have been loaded 
with the address of a field containing the entry name. The name must be left- 
adjusted and padded with blanks to equal the longest allowable station name. 
Permissible registers are 0, 2 through 12, 14, and 15. 



Function: Specifies the name of the work area into which the contents of the 
terminal table entry and its associated option fields are to be placed. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: If register notation is used, the register must previously have been loaded 
with the address of the work area. Framing parentheses must be coded. Permissi- 
ble registers are 1 through 12, 14, and 15. 
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ICOPY 



The ICOPY macro 

• permits examination of the contents of an invitation list; 

• is optional in a TCAM application program. 

The ICOPY macro moves the contents of a designated invitation list to a work 
area. The function of ICOPY is not provided by the operator control facility. 
However, the ACTVATED and STATDISP operator commands cause display of 
the active and inactive terminals in a list and the status byte of an invitation list, 
respectively. Execution of ICOPY alters the contents of registers 14 and 15. 

One of the following codes is returned to the application program in register 15 
after the ICOPY macro is issued: 

Code Meaning 

X^OOOOOOOO' The ICOPY macro executed successfully. 

X'00000004' An invalid relative line number is specified in the rln field of 

the ICOPY macro. 
X^00000008' TCAM is not in the system. 

X'00000020' The name specified is not the name of an opened, TCAM line 

group DCB. 

For a complete description of the invitation list, see Defining Terminals and 
Line Control Areas. 

Figure 33 below illustrates the format of an invitation list with three entries. 
Individual fields in the invitation list are discussed following the illustration. 
Control Information: 

Byte Meaning 

Indicates the total number of entries (both active and inactive) in this 
invitation list. All zeros in this byte indicates that this invitation list is for 
an output-only line (stations on this line cannot enter messages). This 
invitation list contains three entries. 

1 Indicates the number of active entries in this invitation Hst (an active 
entry is one that is currently eligible to be polled). This invitation list 
contains two active entries. 

2 Indicates the number of bytes, including a one-byte index used by TCAM, 
in each entry in this Hst. The sample invitation Hst in the illustration 
above contains entries of three bytes each. The index byte must be the 
last byte in each entry. 

3 Bits through 5 in byte 3 are control bits used by TCAM (their contents 
mustnot be altered). If bit 6 is on, this is an active invitation list (it is 
being polled); if it is off, this invitation Hst is not currently eligible to be 
polled. If bit 7 is on, the Auto Poll feature is being used on the line corre- 
sponding to this invitation list; if it is off, programmed polling is in effect 
(this bit is meaningless if bit 6 if off). Bits 6 and 7 are both on in the 
sample invitation list, thus, this Hst is currently being polled by using the 
Auto PoH feature. 



i 
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Control 
Information 



Active 
Entries 



Delimiter 



Inactive 
Entries 



X'03' 



X'02' 



X'03' 



T 



CPU identifier ■ 

J I 



byte: 



TCAM control bits 

I I I I I 



bit: 1 2 3 4 5 6 7 



polling 
characters 

L_ 



H 


X'FE' 


H 


H 




U 



14 15' 



poi I ing 
characters 



15 



16 



1-byte 
index used 
by TCAM 



polling 
characters 



10 



12 



1-byte 
jndex used 
by TCAM 



17 



1-byte 
index used 
by TCAM 



13 



14* 



Figure 33. Sample Invitation List Containing Three Entries 



4-7 For non-buffered terminals, bytes 4 through 7 contain either ail zeros or 
the address of a field that identifies the central processing unit into which 
TCAM is loaded. For buffered terminals, bytes 4 through 7 indicate the 
following: 

Byte Meaning 

4 A one-byte count of the terminals on this line to which TCAM is current- 
ly sending. 

5 Contains X'Ol' if the line is eligible for Auto Poll. 

6 (unused) 

7 A one-byte count of the total number of terminals on the line. 
The contents of bytes 4 through 7 must never be altered. 

Active Entries: 

Byte Meaning 

8-10 Bytes 8 through 10 represent the first active entry in this invitation list. 

The polling characters for a station (or a component) are contained in the 
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11-13 



two-byte field starting at byte 8; although all the entries in this list use 
two-byte fields to contain polling characters, other lengths may be used. 
Byte 10 contains an index used by TCAM; this index must not be altered. 

Bytes 1 1 through 1 3 represent the second active entry in this sample 
invitation Hst. (The same general discussion of bytes 8-10 also applies 
here.) 



symbol 



grpname 



Delimiter: 

Byte Meaning 

14 For an invitation list containing entries for BSC devices, an EOT charac- 

ter followed by XTE' serves as a delimiter to indicate the end of the list 
of active entries. For start-stop devices, the delimiter is XTE' without an 
EOT character. 

In this sample invitation list, entries are for start-stop devices. Two, active, 
three-byte entries precede the delimiter, and byte indicates that there are three 
entries; consequently, there is a third entry in this invitation list (and since it 
follows the delimiter, it is an inactive entry). The delimiter must not be altered. 

Inactive Entry: 

Byte Meaning 

15-17 Bytes 15 through 17 represent the first inactive entry in this invitation list. 
(The same general discussion of bytes 8-10 also appHes here, except that 
this is an inactive entry.) 

ICOPY has the following format: 



Name 


Operation 


Operands 


[symbol] 


ICOPY 


grpname,rln,areaname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the Une group containing the line whose invita- 
tion Hst is to be displayed. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols, and be the 
same as that specified in the DDNAME= operand of the DCB macro for the hne 
group. 

Notes: If register notation is used, the register specified must have previously 
been loaded with the address of a field containing the grpname . Permissible 
registers are 1-12, 14, and 15. Framing parentheses must be coded. The name 
must be left-adjusted and padded with blanks to eight characters. 
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rin 



Function: Specifies the relative line number, within the line group, of the line 
whose invitation list is to be displayed. 
Default: None. This operand is required. 
Format: Unframed decimal integer greater than zero. 
Maximum: 255 

Notes: If register notation is used, the relative line number must previously have 
been loaded (in binary form and enclosed in parentheses) in the register designat- 
ed. Permissible registers are 0, 2 through 12, 14, and 15. 



Function: Specifies the name of the work area into which the designated invita- 
tion Ust is to be moved. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 
Notes: The number of bytes to be allowed for each entry in the list depends upon 
the type of entry in the Ust. 

If register notation is used, the register number specified must be enclosed in 
parentheses and must contain the address of the work area. Permissible registers 
are 2 through 12, 14, and 15. 
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QCOPY 



The QCOPY macro 

• permits examination of a queue control block; 

• is optional in a TCAM application program. 

QCOPY causes the contents of both a destination queue control block (QCB) and 
its related priority QCBs to be copied into a designated work area. The QCB is an 
internal TCAM control block associated with a destination queue. For a complete 
description of queue control blocks, see the discussion in Section 5, Data Area 
Layouts in the TCAM PLM . A master QCB is 40-bytes and always has associat- 
ed with it at least one priority QCB (even if priorities are not specified for this 
destination QCB's corresponding station in the station's LEVEL= operand of its 
TERMINAL macro). Each priority QCB is 28 bytes; therefore, the formula for 
determining the number of bytes needed in the work area in the user's application 
program is: 

68 + 28n bytes 

where n is the number of different priorities specified (for the station whose 
associated QCB is being copied) in the station's LEVEL= operand of its 
TERMINAL macro. 

Part of the function of QCOPY is also provided by the QSTATUS and 
RLNSTATN operator commands (see their descriptions in the Operator 
Commands section of the chapter Using TCAM Service Facilities), 

One of the following return codes is passed to the application program in register 
15 after the QCOPY macro is issued: 



Code 

X'OOOOOOOO' 
X'00000004' 

X'00000008' 
X'OOOOOOOC 

X'00000020' 



X'00000080' 



Meaning 

The QCOPY macro executed successfully. 

Invahd terminal table entry type (for example, distribution Ust 

or cascade Ust is specified in the termname field). 

Invahd terminal table entry type (for example, distribution list 

A TCAM application program DCB is not open; for this macro 

to execute, at least one input or output DCB must be open. 

An invalid station name is specified in the termname field of 

the QCOPY macro (that is, no such entry exists in the terminal 

table). 

The iterative process has been completed the number of times 

specified by the LIMIT=operand. 



QCOPY has the following format: 



Name 


Operation 


Operands 


[symbol] 


QCOPY 


termname ,areaname[,LIMIT= (integer ) ] 

((register)/ 



i 
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symbol 



termname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the terminal table entry whose QCB is to be 

displayed, or the name of the last terminal table entry that had its QCB displayed 

if using iterative processes and selection criteria. See notes following the LIMIT= 

operand. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 

identical to the name of the terminal table entry. If using iterative processes and 

selection criteria, must be blank. If register notation is used, the specified register 

number must be enclosed in parentheses, and the register must contain the address 

of a field containing the name of the entry. The name must be left justified and 

padded with blanks to the length of the longest allowable station name in the 

table. 



LIMIT=rinteger )^ 
I (register) ) 



Function: Specifies the name of the work area into which the contents of the 

designated QCB are to be placed. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. If register 

notation is used the specified register number must be enclosed in parentheses, 

and the register must have been loaded previously with the address of the work 

area. Permissible registers are 2 through 12. 

Function: Indicates that an interactive process and selection criteria are to be 
used. The number specified is the minimum number of messages for which the 
routine will select a terminal table entry. 
Default: None. Specification optional 
Format: LIMIT=integer or LIMIT = (register) 
Minimum: 1 
Maximum: 4095 

Notes: If register notation is used a register number may be enclosed in parenthes- 
es or a symbol equated to a register number may be enclosed in parentheses. 
Registers 2 through 12 may be used. If this operand is not coded, the QCOPY 
routine will display the QCB for the designated terminal name. If coded, a 
terminal name subsequent to the one specified in operand 1 with at least the limit 
number of messages in its queue will be returned in the original terminal name 
area and its QCB will be displayed. 

QCOPY iterative processes and selection criteria enable the user to display all 
QCBs for terminals having some threshold number of messages queued. The 
threshold is specified in the LIMIT = operand. 
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TCHNG 



symbol 



The TCHNG macro 

• places specified data in a terminal table entry and its associated option fields; 

• is optional in a TCAM application program. 

TCHNG causes the contents of a designated work area to replace the contents of 
a specified terminal table entry. The TCOPY macro may be used to move the 
contents of a terminal table entry to a work' area where the contents are manipu- 
lated as desired (see the discussion of the TCOPY macro for a description of a 
terminal table entry). The TCHNG macro is then used to move the modified 
entry back to the terminal table. Option fields are modified in the same manner 
by this macro. 

All necessary information for proper execution of TCAM must be placed in the 
terminal-table entry in proper form. The contents of option fields may also be 
modified by the DATOPFLD operator command (see the Operator Commands 
section of this publication). 

One of the following return codes is returned to the application program in 
register 15 after the TCHNG macro is executed: 

Code Meaning 

X'OOOOOOOO' The TCHNG macro executed successfully. 

X'00000008' TCAM is not in the system. 

X'OOOOOOOC A TCAM application program DCB is not open; at least one 

input or output DCB must be open for this macro to execute. 

X'00000014' Either a) an invalid protection password is specified as the 

PASSWRD= operand of the TCHNG macro; or b) the 
PASSWRD= operand is not specified in the TCHNG macro 
(and it must be specified because the INTRO macro's 
PASSWRD= operand specifies a protection password; code 
this operand exactly as it is coded in the INTRO macro). 

X'00000020' An invalid station name is specified in the termname field of 

the TCHNG macro (that is, no such entry exists in the terminal 
table). 



TCHNG has the following format: 



Name 


Operation 


Operands 


[symbol] 


TCHNG 


termname,areaname [,PASSWRD= chars] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



{ 
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termname 



PASSWRD=chars 



Function: Specifies the name of the terminal table entry whose contents are to be 
replaced by the contents of the designated work area. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 
identical to the name of the station as specified in the terminal table. 
Notes: If register notation is used, the specified register number must be enclosed 
in parentheses, and the register must contain the address of a field containing the 
name of the terminal table entry, left-adjusted and padded with blanks. The field 
must be as long as the longest allowable station name, a maximum of eight charac- 
ters. Permissible register are 2 through 12. 



Function: Specifies the name of the work area from which the information is to 

be moved into the terminal table entry. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: The first byte of the entry receives the first byte of data in the work area, 

which must accordingly be the status byte. The work area should be at least as 

long as the longest terminal table entry that will be changed. 

If register notation is used, the specified register number must be enclosed in 
parentheses, and the register must contain the address of the work area. Permissi- 
ble registers are 2 through 12. 

The new entry must contain, in proper form, all information necessary for success- 
ful operation of TCAM. See the description of the terminal table entries in the 
chapter Defining Terminal and Line Control Areas. 



Function: Specifies the protection password that enables only qualified applica- 
tion programs to issue the macro. 

Default: None. If the PASSWRD= operand of the INTRO macro was coded, 
this operand is required. Otherwise, specification optional. 
Format: One to eight, nonblank characters, unframed. 

Notes: If coded, this operand must specify the same characters as were specified 
in the INTRO macro. 
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ICHNG 



The ICHNG macro 

• modifies an invitation list; 

• is optional in TCAM application programs. 

ICHNG causes the contents of a designated work area to replace the contents of a 
specified invitation Hst, or the stations in the specified list to be activated or 
deactivated for entering messages (if they are polled stations). ICOPY macro may 
be used to move the contents of an invitation list to a work area where the con- 
tents are manipulated as desired. The ICHNG macro may then be used to move 
the modified Ust contents back to the invitation Ust. For a complete description of 
the invitation hst, see Establishing Contact in the chapter Defining Terminal 
and Line Control Areas in this book. A sample invitation list containing three 
entries is presented in the discussion of ICOPY. 

If the macro is used to replace the contents of a specified invitation hst with the 
contents of a work area, all necessary information for proper execution of TCAM 
must be placed in the invitation Hst in proper form. Entries in an invitation list 
may also be activated or deactivated by the ENTERING, NOENTRNG, 
NOTRAFIC, and ACTVBOTH operator commands. The Auto Poll facility may 
be activated or deactivated by the AUTOSTRT and AUTOSTOP operator 
commands, respectively (if the autopoll bit is turned on in the UCB). See the 
description of these commands in the Operator Commands section of this publi- 
cation. Stopping and starting of Unes before and after changing the contents of an 
invitation Hst is handled automaticaUy for the TCAM user. Execution of ICHNG 
alters the contents of registers 14 and 15. /^ 



One of the f oUowing codes is returned to the appHcation program in register 1 5 
after the ICHNG macro is issued: 

Code Meaning 

X^OOOOOOOO' The macro executed successfuHy. 

X*0000000r The DCB for the line group specified by grpname is not open. 

X*00000004' An invaHd name is specified for the grpname operand of the 

ICHNG macro. 
X*00000008' An invalid relative Hne number is specified in the rln field of 

the ICHNG macro (that is, no such relative number exists for 

the group). 
X^OOOOOOOC TCAM is not in the system. 

X'00000014' The PASSWRD= operand is not specified or is specified 

incorrectly in the ICHNG macro (and it must be specified 

because the INTRO macro's PASSWRD= operand specifies a 

protection password; code this operand exactly as it is coded in 

the INTRO macro). 
X'00000020' The grpname is invalid. 

ICHNG has the following format: 



i 



i 
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symbol 



grpname 



rln 



Name 


Operation 


Operands 


[symbol] 


ICHNG 


grpname,rln,^areaname| 
.^ACT > 
(dEACT )[,PASSWRD=chars] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the line group containing the line whose invita- 
tion list is to be modified. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and be 
identical to the name specified on the DD statement associated with the line 
group. 

Notes: If register notation is used, the specified register number must be enclosed 
in parentheses, and the address of a field containing the grpname must previously 
have been loaded into the general register specified. The name must be left- 
adjusted in the field and padded with blanks to equal eight bytes. Permissible 
registers are 1 through 12, and 14. 

If the DCB for the line group has not been opened, ICHNG is not executed and a 
return code of X'OT is set in register 15. 



Function: Specifies the relative line number within the Une group of the Hne 

whose invitation list is to be modified. 

Default: None. This operand is required. 

Format: Unframed decimal integer greater than zero. 

Maximum: 255 

Notes: If register notation is used, the register number specified must be enclosed 

in parentheses, and the register must previously have been loaded with the relative 

line number in binary format. Permissible registers are 1 through 12, and 14. 



areaname 

ACT 

DEACT 



Function: Specifies the type of modification or the modification itself. 

Default: None. This operand is required. 

Format: areaname, ACT, or DEACT. areaname must conform to the rules for 

assembler language symbols. 

Notes: areaname specifies the name of the area that contains the new invitation 

list. The first byte of the invitation hst receives the first byte of the data in the 

work area, which accordingly must be the first byte of the invitation list control 

word. 






ACT causes the activation of all entries in the specified invitation list. DEACT 
causes deactivation of all entries in the specified invitation Ust. No further polUng 
will occur until the list is reactivated by an ICHNG macro specifying ACT, or an 
ENTERING operator command. 
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Register notation may be used for areaname . If register notation is used, the 
specified register number must be enclosed in parentheses, and the address of the 
work area must previously have been loaded into the register specified. Permissi- 
ble registers are 1 through 12, and 14. 

If areaname is specified, the new invitation list must contain, in proper format, all 
information necessary for successful operation of TCAM. See the description of 
the ICOPY macro for the format of the control word and of an invitation list. 

PASSWRD=chars 

Function: Specifies the protection password that enables only qualified applica- 
tion programs to issue the macro. 

Default: None. If the PASSWRD= operand of INTRO was coded, this operand 
is required. Otherwise, specification optional. 
Format: One to eight nonblank characters, unframed. 

Notes: If coded, this operand must specify the same characters as specified by the 
PASSWRD= operand of INTRO. If the characters do not agree, or if INTRO 
specified PASSWRD= but this macro does not, ICHNG does not execute. 



^ 
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symbol 



MRELEASE 



The MRELEASE macro 

• releases messages queued for a destination, 

• reactivates a destination made inactive by a HOLD macro or a SUSPXMIT 
operator command. 

The MRELEASE macro releases messages queued for a station. This macro has 
the same effect as the RESMXMIT operator command. 

One of the following codes is returned to the appHcation program in register 1 5 
after the MRELEASE macro is issued: 

Code Meaning 

X'OOOOOOO' The MRELEASE macro executed successfully. 

X*000000r There is no open DCB in the program. 

X* 0000004' The MRELEASE macro did not execute because the station is 

already receiving its queued messages. 
X^OOOOOOC TCAM is not in the system. 
X*0000014' The MRELEASE macro did not execute because either 

a) the protection password specified in the PASSWRD= operand 
does not match the protection password specified by the 
PASSWRD= operand of the INTRO macro, or 

b) a protection password is not specified in the PASSWRD= 
operand of the MRELEASE macro (and it must be specified 
because the INTRO macro's PASSWRD= operand specifies a 
protection password). Code the PASSWRD= operand exactly as 
it is coded in the INTRO macro. 

X'0000018' The MRELEASE macro did not execute because 

a) statname is not a single entry in the terminal table, 

b) there is no HOLD macro in the system, or 

c) the station uses main-storage queues only. 

X'0000020' The MRELEASE macro did not execute because an invalid station 
is specified in the statname field of the macro. 

MRELEASE has the following format: 



Name 


Operation 


Operands 


[symbol] 


MRELEASE 


statname [,PASSWRD= chars ] 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



statname 






Function: Specifies the name of the station that is now to receive its queued 

messages. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols and be the 
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PASSWRD== chars 



same as the name of the terminal entry. 

Notes: If register notation is used, the address of a location containing the name 

of the station must be placed in the general register, 2 through 12, that is indicated ^ 

in parentheses. The name must be left-adjusted and padded with blanks to the 

length of the longest station name. 

Function: Specifies the protection password that enables only qualified appHca- 

tion programs to issue the macro. 

Default: None. Specification optional. 

Format: One to eight nonblank, unframed characters. 

Notes: If the PASSWRD= operand is specified on the INTRO macro in the 

MCP, this operand must be specified and must be same as the INTRO value. If 

they do not match or if this operand is omitted, but a value is specified for 

INTRO, the MRELEASE macro does not execute. 

TCAM's Message Retrieval Facility 

During the operation of a telecommunications system, it may be necessary to 
retrieve a message that has already been placed on a destination queue located in a 
message queues data set on any combination of reusable and nonreusable disk. 
Messages cannot be retrieved from main-storage-only queues. TCAM uses a 
combination of POINT with GET or READ macro instructions to retrieve the 
desired message. After the message has been retrieved, user code may process it 
as appropriate and direct it to a desired destination. The message may be re- 
trieved, whether or not it has already been sent to its destination, provided that 
the entire message has been queued on disk at the time that the POINT macro is 
executed. 

If the application-program work area is too small to contain the entire message, i 

the next GET or READ macro referring to the same DCB retrieves the rest of the 
message if C is specified in the OPTCD= operand of the appropriate input DCB 
macro. If C is not specified, the SYNAD= exit is taken. If the user does not want 
the appHcation program to retrieve the rest of the message, he may so specify by 
issuing a POINT macro whose address operand points to a block containing the 
station name followed by a X'40' (see the description of the address operand of 
the POINT macro below). 

Since an output sequence number is not assigned to a message until it is actually 
sent to the destination, no message can be retrieved by output sequence number 
until it has been sent. 



( 
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POINT 



The POINT macro 

• returns a station identification to the application program. 

The POINT macro is used in conjunction with GET or READ to identify a station 
by passing, in a register or a field, the station identification and the sequence 
number of the message to be retrieved. Registers that may be altered during 
execution of the POINT routine are 0, 1, 14, and 15. A multiple retrieval facility 
allows the user to request the return of all information in the queue back-chain. 
The user is responsible for examining this information to find the desired message. 
The queue-back chain is a time-sequential record of the sending and receiving 
message traffic for the terminal or terminals of a specific destination QCB. 
TCAM maintains this chain for the message retrieval function of application 
programs. A message that has already been sent can be retrieved by source (input) 
or by destination (output) sequence number. 

The advantage of using multiple retrieval is a reduction in the number of disk 
accesses to retrieve more than one message. 

To perform multiple retrieval an application program will set up the required input 
to the POINT macro (setting the high-order bit in the sequence number field to 
trigger the function) and issue the POINT macro followed by a GET or READ 
macro for each message. The sequence is: 



POINT POINT 

READ READ 

not 

POINT READ 

READ READ 



The user does not reinitialize the POINT macro fields for each message. 

The following information is moved into the user work area in front of each 
retrieved message: 



Field Number of bytes 

Source offset 2 

Message status 1 

Input sequence number 2 

Output sequence number 2 

Destination offset 2 

Number of reserves 1 



The field definitions are: 



Writing TCAM-Compatible Application Programs 433 



Source offset is the index value into the termname table for the source terminal. 

Message status is a byte containing the following information needed by the user. 
The TM instruction should be used for testing this byte. Bit combinations not 
shown should be ignored by the user. 

X*Or Not the first buffer of a message. 

X'02' Not the last buffer of a message. 

X'08' Duplicate header. 

X*40' Error message is in this buffer. 

X*80' Cancel message has been executed. 

Input sequence number provides a means of ensuring that messages are received 
from a source in the correct order. 

Output sequence number is placed in the neader of a message by TCAM that 
determines the order in which messages were sent to a destination by the 
computer. 

Destination offset is a two-byte index to the termname table entry of a destination 
or station. 

Number of reserves (see the RESERVE^ operand of the line group 
DCB macro). 

One of the following codes is returned to the application program in register 15 
after the POINT macro is issued: 

Code Meaning 

X'OOOOOOOO' The POINT macro executed successfully. 

X*00000004' No message having the specified sequence number is queued in 

the specified destination queue. 
X*00000008' The destination name specified is not a valid entry in the terminal 

table. 
X*0OO00OOC' 1 ) The specified destination queue is not located in a data set 
residing on disk. 

2) The user tried to specify GET process entry as the message 
source (that is, he specified I in conjunction with the name of a 
GET process entry). 

3) The user tried to specify PUT process entry as the message 
destination (that is, he specified O in conjunction with the 
name of a PUT process entry). 

4) DISK=NO was specified on the INTRO macro instruction. 

POINT has the following format: 



Name 


Operation 


Operands 


[symbol] 


POINT 


dcbname, address 



i 
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svmbol 



dcbname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the data control block in the application program 
for the subsequent GET or READ associated with the POINT macro. 
Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and must 
agree with the name of the DCB macro for the associated data control block. 
Notes: If register notation is used, the address of the data control block must 
previously have been loaded in register 1, or 2 through 12. The register must be 
coded within framing parentheses. 



address 



Function: Specifies the symbolic address of a field needed for the POINT macro. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols. 

Notes: address is the symbohc address of a field containing a block with three 

contiguous fields: 

1 . An eight-byte field containing the station name, left-adjusted and padded with 
character blanks (X'40'). 

2. Either I (X'C9') or output sequence number, respectively. This field contains a 
blank (X'40') for retrieval termination. 

3. A two-byte binary sequence number, right-adjusted with leading binary zeros. 
If register notation is used, the address of this area must previously have been 
loaded in a register, 1 through 12. Framing parentheses must be coded. 

TCAM'S Inquiry/Response Facilities 

TCAM provides two means of achieving inquiry/response interactions between a 
station and an application program. One, called line lock , involves estabHshing a 
physical connection between a station and an application program, and maintain- 
ing this connection for the duration of the conversational interaction. Line lock, 
achieved by a LOCK macro, renders the line unavailable to other stations for the 
duration of the conversational interaction. 

The other means is called terminal lock. Terminal lock involves establishing a 
logical connection between a station and an application program so that the 
station receives responses to its inquiries without tying up the line. Terminal lock, 
achieved by use of HOLD and MRELEASE macros used in conjunction with 
TCAM's message priority scheme, assures the station that the next message it gets 
after it enters an inquiry is the response to that inquiry, but does not render the 
line unavailable to other stations while the inquiry is being processed. The 
terminal lock capability can be used by stations taking advantage of TCAM's 
buffered terminal support, whereas the line lock capability cannot. 



Line Lock 



TCAM can maintain a connection between a station and an application program 
for a period of time not less than the duration of the message and its response. 
This feature is called lock mode, and is supplemented by a hardware feature 
known as conversational mode. In this mode, a station is able to accept a text 
response to an inquiry message without having to be selected before receiving the 
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response. Lock mode and the conversational feature are complementary functions. 
Both shorten the interval between an inquiry and its response. 

( 
Lock mode is used for inquiry applications. For fastest response, the station 
remains on the line until an application program returns the required information. 
While the station is in lock mode, no incoming messages are accepted from any 
other station on the line, and no outgoing messages other than the response 
message are sent to any station on the line (including the station in lock mode). 
Many stations on other lines may be simultaneously locked to the same apphcation 
program. 

There are two types of lock mode — message lock and extended lock. The desired 
function is specified by an operand of the LOCK Message Handler macro instruc- 
tion. 

If the station is in message lock mode, the connection is maintained while the 
entire message is sent to an application program and until the response message 
arrives. The first message from the application program to arrive at the destination 
queue for the locked station is assumed to be the response. The line is automati- 
cally freed when the response has been sent. 

In extended lock mode, the same station is polled again after the response has 
Deen sent to it. If the response is positive, the next inquiry message is entered by 
the station. If the response is negative, the station is repoUed until a positive 
response is received. Lock mode is maintained until an UNLOCK macro is issued. 

Once a station is in extended lock mode, all messages entered by it are assumed to 
be inquiry messages directed to the application program to which the station is 4 

locked. Destinations specified in the headers of messages and checked by a 1 

FORWARD macro are overridden when the station is in extended lock mode. 
Therefore, once extended lock mode is in effect, the FORWARD macro must be 
executed after the UNLOCK macro to be effective. 

Message lock is used if a single inquiry will provide all the information required. 
For instance, an inventory application might handle inquiries requesting the 
quantity of a certain part in stock. Extended lock mode is used if a series of 
inquiries must be made, each requiring a response. In a credit application, the 
inquiries might ask if a person has an account, await verification, and then request 
the credit balance. (Lock mode is not supported for stations using TCAM's 
buffered terminal support by specifying the BFDELAY= operand of their 
TERMINAL macros.) 

Either form of lock mode may be entered unconditionally or conditionally. 
Conditional execution occurs when a message header containing a control charac- 
ter or character string is processed by a LOCK macro specifying that character. 

The UNLOCK macro is used to remove a station locked to an apphcation program 
from extended lock mode. It may also be issued either unconditionally or condi- 
tionally depending upon a control field specified by both macro and message 
header. When used in an inmessage or outmessage subgroup, the UNLOCK macro 
function depends on the occurrence of a specified error, or it may be specified 
unconditionally. See the conchars operand of the UNLOCK macro. 

If a station locked to an apphcation enters a message and a quick closedown is » 

initiated or the line is stopped by operator control, the response is received before 
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the station is deactivated. If the application program data set is closed, TCAM 
automatically disconnects from lock mode all stations locked to that application 
program using the deactivated data set. 

The user must issue a valid PUT, CLOSE, or WRITE macro for each lock inquiry 
in order for a line to be eligible to be stopped. 

The various forms of lock mode are summarized in the following table. 





Message Form 


Extended Form 


CONDITIONAL 


Coded: LOCK 


Coded: LOCK 




MESSAGE, A 


EXTENDED, B 




Locked: When LOCK is 


Locked: When LOCK is 




executed, if A is the 


executed, if B is the 




next character in the 


next character in the 




header of the message 


header of the message 




currently being handled 


currently being handled 




by inheader subgroup. 


by inheader subgroup. 




Unlocked: When response 


Unlocked: On 




has been sent. 


execution of an 
UNLOCK macro. 




/Coded: LOCK MESSAGE 


/ Coded: LOCK EXTEND 


UNCONDITIONAL 
EXECUTION 


\Locked: When LOCK is 
/executed. 


\ Locked: When LOCK is 
/executed. 




' Unlocked: When response 


\ Unlocked: On 




has been sent 


execution 

of an UNLOCK macro. 



The conversational mode feature is specified by the CONV= operand of the 
STARTMH macro. When the computer receives a message from a station using 
this feature, instead of sending the normal positive acknowledgment, the computer 
sends a response message (from an application program) to the station. The 
station interprets this as a positive response. Transmission in this manner saves 
two Hne turnaround sequences. 

If conversational mode is specified, a logical block of data being entered by a 
station is treated by TCAM as if it were a complete message. That is, an EOB or 
ETX line-control character is assumed to be an EOT. Conversational mode may 
occur only for receiving and is operative only if the station is placed in lock mode 
when the message is processed by the inheader subgroup. 

Conversational mode may be specified unconditionally (CONV=YES) or condi- 
tionally by the use of an option field. The CONV= operand specifies a bit setting 
and a one-byte option field. If any of the bits in the option field are on, conversa- 
tional mode will be used for this Message Handler. (If the option field is longer 
than one byte, the first byte in the field is the one tested.) 
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If logical messages are handled by the inheader subgroup in which a LOCK macro 
appears, only those logical messages formed by blocking two or more incoming 
physical transmissions may be processed (and the inblock subgroup's SETEOM 
macro must specify PROCESS=NO). Logical messages are discussed in 
Handling Logical Messages in this chapter. Line lock is achieved after TCAM 
detects the EOM character ending the logical message — thus, several physical 
messages may arrive at the CPU before Une lock is established. To achieve 
conversational mode, specify CONV=YES in the STARTMH macro, and 
QBY=T in the TERMINAL macro for the source station. 

An example of an MCP and an application program using message lock and 
conversational mode is shown in the Sample MCPs section. 

There are several coding considerations for the three macro instructions involved 
in utilizing TCAM's inquiry/response facility. They are based upon the type of 
station being used, the logic of the application program, and the interaction with 
other Message Handler macro instructions. These considerations are summarized 
here. 

LOCK 

• Required for audio terminals. 

• Is suggested for a 3735 attached to a switched line. 

• Cannot be used with any station using TCAM's buffered-terminal support. 

• Should not be used if the logic in the application program requires that certain 
inquiry messages not be provided a response (when a station sends an inquiry 
in lock mode, an application program must send a response to the inquiry 
station, otherwise, the Hne may be lost either to the inquiring station, or to 
another station to which the application program may erroneously send the 
response). 

• Requires the user to specify a destination in the destination field in the work 
area, and to code a FORWARD macro having a DEST= operand specifying 
DEST=PUT in the incoming group of the MH for the apphcation program. 

• If the originating terminal is an IBM 2260 Local terminal, the entire line group 
is placed in lock mode. If another 2260 Local in the Une group attempts to 
enter a message, the read request is recognized and queued for later servicing. 
However, the message will not be received from the second 2260 until a 
response message has been sent to the originating 2260. 

• If a station on a switched line breaks the line connection by hanging up while in 
extended lock mode, the Une is unavailable for transmission to or from any 
stations unless UNLOCK has been specified in the inmessage or outmessage 
subgroup with the optional disable function. To render the line available for 
further transmission, issue a STOPLINE operator command for the line, and 
then issue a STARTLINE operator command to reactivate the line. 

• If the CANCELMG macro is executed in the inmessage subgroup for a lock 
message, the lock is not broken, and the station wiU be repolled. 

• If the HOLD macro is executed in the outmessage subgroup for a lock re- 
sponse, the lock is not broken, the terminal is not held, and the message wiU be 
retransmitted immediately (that is, it wiU be sent twice). This can result in an 
infinite loop if the condition for HOLD is permanent and the line or station is 
inoperative. 

• If a station is held by an operator command while in lock mode, or if a lock is 
initiated while the station is held, aU lock responses will be sent as if the station 
were not held. No other messages wiU be sent until the station is released. 

• The user must issue a valid PUT, CLOSE, or WRITE macro for each lock 
inquiry in oder for a line to be eUgible to be stopped. 

• No QTAM network-control macro should be issued in an application program 
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I 



for a line on which is located a station locked to this application program by a 
LOCK macro. If this happens, the locked Hne is lost to the system and the 
application program goes into a wait state. 

UNLOCK 

• When the UNLOCK macro is issued in the inheader subgroup handling inquiry 
messages being received from a station in extended lock mode, the message 
currently being handled is routed to the destination specified in its header, or 
by a FORWARD macro, if UNLOCK is issued before the FORWARD macro 
is issued. If UNLOCK is issued after FORWARD, the message is routed to the 
application program to which the originating station was locked. 

STARTMH 

• CONV=YES should be specified if IBM 1030 or IBM 1060 stations are 
included on lines handled by this Message Handler, since these Unes do not 
have the capability of entering an EOT line-control character after their mes- 
sages. 

• CONV=YES should not be coded if any IBM 2780 station or IBM 2770 
station using TCAM's buffered= terminal support, is included on a line handled 
by this Message Handler. If CONV=YES is coded in either of these cases, 
device hardware assumes an error after a block of data is entered, and retrans- 
mits the same block when next invited to enter data. 



A conversational facility somewhat different from that described above is provid- 
ed by the HOLD/MRELEASE macro combination. When issued in the incoming 
group of a Message Handler, HOLD suspends transmission of outgoing messages 
to the station entering the message until an MRELEASE macro in an application 
program releases the station. The first message sent to the station after 
MRELEASE executes is the highest-priority message on the destination queue for 
the station. (If more than one message is in the highest-priority group, the one 
that was completely enqueued first is sent first.) Thus, by assigning his conversa- 
tional responses a higher priority than is assigned to other messages that might be 
sent to the station, the use of HOLD and MRELEASE can ensure that the next 
message received by a station after it enters an inquiry is the response to that 
inquiry. 

Unlike the inquiry/response capability provided by the LOCK macro, the 
HOLD/MRELEASE capability does not maintain the line connection between a 
station and an appHcation program. This means that the line will be available to 
other stations while a station awaits a response to its inquiry, but it also means 
that if another station is using the Hne when the response to an inquiry arrives at 
the MCP from an application program the response will not be sent until the Hne 
is available. 

The user may prefer to use HOLD/MRELEASE rather than LOCK to achieve an 
inquiry /response capability in the following situations: 

• when his stations make use of TCAM's buffered terminal support (in this case, 
the LOCK macro may not be used); 

• when he is wilhng to sacrifice some response time to have his line available to 
other stations while a response to an inquiry is being prepared. 

HOLD/MRELEASE may also be used to provide a capability similar to that 
provided by the extended lock mode of operation described above. Such a 
capability might be useful, for example, when a buffered terminal on a multipoint 
line requires an inquiry/response operation consisting of multiple pairs of inquir- 
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ies and responses, and when that terminal may be the destination for unsolicited 
(for example, switched) messages that must not interrupt the inquiry/response 
conversation. 

In this situation, the user may multiply define a physical station to TCAM, so that 
the same physical station looks like two separate logical stations to TCAM. He 
does this by coding two separate TERMINAL macros having different names, and 
coding the addressing characters for the physical station in the ADDR= operands 
of both TERMINAL macros. In addition, he places an entry for each of the two 
logical stations created by the two TERMINAL macros in the ORDER = operand 
of the INVLIST macro for the line; each entry specifies the polHng characters for 
the physical station. 

The user would use one of his logical stations as a destination for non- 
conversational messages, and the other as the destination for responses to 
inquiries. When beginning a series of inquiry/response interactions that he does 
not want interrupted by non-conversational traffic, the user could intercept 
message traffic for the logical station assigned to handle non-conversational 
messages with a HOLD macro, carry on hfs conversation between an application 
program and his physical station using the other logical station, and then release 
the non-conversational logical station by executing an MRELEASE macro after 
the conversation is over. 

In a more general way, multiply defined logical stations all referring to the same 
physical station might be used to handle different types of output for that station. 
For example, the user might want to use a physical station to handle switched 
messages and inquiry /response interactions, as described above, and also to print 
out two different kinds of report, each of which requires a special form on the 
station's printer. By defining a separate logical station for each application and 
seeing that all logical stations but one are intercepted with HOLD at any given 
time, the user can ensure that his physical station is getting only the kind of output 
which the logical station currently not intercepted is defined to handle. When he 
wants his physical station to handle a different type of output, the user need only 
execute a HOLD macro for the logical station connected with his current applica- 
tion, and then issue an MRELEASE macro for the logical station connected with 
his new application. 

TCAM's Queue Reset Facility 

During the operation of a telecommunications system, it may be necessary to 
resend messages that have already been transmitted to an output device and 
marked serviced. A temporary hardware problem such as a broken printer ribbon 
may precipitate such a situation. TCAM provides the facility to allow the user to 
request resumption of an output operation at a specified output sequence number. 
Only messages that have been placed on a destination queue located in a message 
queues data set on any combination of reusable and nonreusable disk can be 
resent. 

In addition to the requirement that the queue reside on disk, the other restrictions 
are: 

• there must be no priority level queuing. 

• there must be queing by terminal unless the queue being reset represents an 
application program. 

• the terminal whose queue is being reset cannot be held at the time of the 
QRESET request. 
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• if the queue of an application program is being reset, that application program 
must be closed. 

The user must code an application program that issues the QRESET macro. The 
TPROCESS macro for the application program must have specified 
QBACK=YES. The user must also provide QRESET with the desired output 
sequence number and the name of the output device or the appHcation program 
TPROCESS entry whose queue will be reset. The address of a field containing 
this information must be passed to QRESET in register 2. The format of the field 
is: 

Byte Format Contents 

- 7 Character (left Destination name 

adjusted and 
padded with blanks) 

8 - 9 Hexadecimal Sequence number - maximum 

value= decimal 9999 • 

The requested queue is searched for the sequence number specified. As the queue 
search proceeds backward from the last message queues for the terminal, interven- 
ing message headers up to and including the requested one are marked unserviced 
on disk. Fields are reset to allow TCAM to resend the messages that have been 
successfully processed by QRESET. 

Good morning messages are not available to QRESET. Initiate mode and lock 
mode messages will not be processed for resending. If the requested sequence 
number or any intervening numbers cannot be marked unserviced, the count of 
messages that have been successfully processed by QRESET is returned in register 
2 and the appropriate return code is provided. 

Error conditions that terminate processing the QRESET request are listed in the 
discussion of the QRESET macro. 

The user should be aware that while the queue is being processed by the Queue 
Reset Executor module 

• the application program issuing the QRESET will be put in an OS Wait; 

• output to the terminal whose queue is being processed is suspended. 

There is an important consideration for the user when using the QRESET facihty 
for an output device whose destination message queue resides on reusable disk. 

In searching the message queue for the requested output sequence number, only 
header portions of messages are examined. It is possible that an intact header 
resides on disk but that its text segment has been overlaid as a result of reusable 
disk reorganization. If this situation should exist and if TCAM tries to resend this 
message, a logical read error will occur and TCAM will terminate abnormally (see 
Reusable Disk Queues in the chapter Defining the MCPData Sets), If QRESET 
finds that a header lies within a zone that has been or is about to be reorganized, 
the QRESET function terminates with the appropriate return code. There will be 
no attempt to resend any of the messages that may have been successfully pro- 
cessed by QRESET up to this point. If a header unit may be safely retransmitted, 
. QRESET checks the position of a text or XTRA unit relative to the disk location 

I of the header unit. If it is determined that the text or XTRA unit is far enough 

behind the header to present problems when resending, QRESET does not mark 
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the message unserviced. However, processing of remaining requested messages 
continues. 

To use QRESET with the least impact on the issuing application program, the 
terminal whose queue is being searched, and the overall processing time, it is 
recommended that the QRESET f aciUty be used to resend a small number of 
messages that have been recently transmitted. Recent would have to be judged in 
terms of message traffic on the message queues data set and to the specified 
output device. 



( 



442 OS/MFT and OS/MVT TCAM Programmer's Guide 



QRESET 



The QRESET macro 

• re-sends messages to an output device whose message queue resides on reusable 
or nonreusable disk; 

• may alter registers 0, 1,2, and 15 during the execution of the QRESET func- 
tion routines. 

QREI^ET has the following format: 



Name 


Operation 


Operands 


[symbol] 


QRESET 


dcbname,MAX= integer 



symbol 



dcbname 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary). 

Function: Specifies the name of an opened DCB in the application program 

issuing the QRESET. 

Default: None. This operand is required. 

Format: Must conform to the rules for assembler language symbols and must 

agree with the name of an opened DCB that is defined in the application program. 

Note: If register notation is used, the address of the DCB must have been loaded 

previously in one of the registers 3 through 12. The register must be coded within 

framing parentheses. 



MAX = integer 



Function: Specifies the maximum number of messages that may be resent from 

the destination queue of the output device. 

Default: None. This operand is required. 

Format: Decimal value greater than zero and less than or equal to 9999. 



One of the following codes is returned to the appUcation program in register 15 
after QRESET has been issued: 



Code Meaning 

X^OOOOOOOO' QRESET has executed successfully. 

X'00000004' QRESET has been unable to mark unserviced 

some of the range of output sequence numbers. Register 2 
contains the count of messages successfully processed by 
QRESET. 
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Code Meaning 

X'00000008' Reusable disk reorganization is in progress. Register 2 contains 
the count of messages successfully processed by QRESET prior 
to the start of reorganization. 

X*OOOOOOOC' The requested output sequence number is invaUd for one of the 
following reasons: 

• higher than the last sequence number received at the specified 
output device. 

• exceeds QRESET MAX= value. 

• is zero. 

• is not marked "serviced." 

X*00000010' QRESET is not allowed from this application program because 
QBACK=YES was not specified on the TPROCESS macro. 
QRESET request for an open application program. 

X*00000014' Either the specified output device or TPROCESS entry name 
is invalid or the device is being held. 

X*00000018' An error condition regarding the type of queuing has been detected 
or there are no messages queued for the specified terminal. 

X'OOOOOOIC QRESET function has been prematurely terminated because one 
of the headers requested may not be available due to reusable 
disk reorganization. Any messages found successfully up to this 
point have been marked unsefviced but will not be scheduled to 
be re-sent by QRESET. 

TCAM/SAM Compatibility 

TCAM gives the user the capability of testing his appHcation programs in a 
non-teleprocessing environment and then running them in conjunction with a 
TCAM MCP. (An example would be exercising the logic of a TCAM application 
program by using input from a card reader with output going to a printer.) In 
many cases, the user can convert from a non-TP to a TCAM environment merely 
by changing the DD statements for his application-program data sets. 

If you intend to run a TCAM application program in a non-TP environment, you 
should remember the following points: 

1. The OPTCD= operand of the DCB macro has incompatible meanings in a 
non-TP and a TCAM environment. Therefore, this operand should be omitted 
from the DCB macro and specified if needed at execution time by the DCB= 
parameter of the DD statement. 

2. Test data for the non-TP environment should contain any optional fields that 
would be present in the work area if the program were run under TCAM, for 
the space in the work area allocated to optional fields to be filled. 

3. The POINT macro must not be issued in a non-TCAM environment. 

4. When issued in a non-TCAM environment, the TCOPY, ICOPY, QCOPY, 
TCHNG, ICHNG, MRELEASE, and MCPCLOSE macros merely place a 
return code in register 15 indicating that TCAM is not in the system, and pass 
control to the next instruction. 

5. The DCB checkpoint exit is ignored in a non-TCAM environment. 
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Coordinating TCAM Checkpoints of the MCP with OS Checkpoints of the Applica- 
tion Programs 

TCAM checkpoints of the Message Control Program may be coordinated with OS 
checkpoints of TCAM appUcation programs by CKREQ macros issued in the 
apphcation programs. The purpose of coordination is to allow the MCP and each 
apphcation program to restart at the same point following system failure. This 
section describes how the CKREQ macro is used to ensure coordination between 
application program and MCP, and also how a user-specified exit from the input 
or output DCB macro for the application program may be used for this purpose. 
For more information on the TCAM checkpoint/restart facihty, see the chapter 
Using TCAM Service Facilities . The OS checkpoint facility is described in the 
Advanced Checkpoint /Restart Planning Guide. 

When external files are updated by the contents of messages sent to an application 
program, coordination of the contents of the files, the appUcation-program 
environment, and the messages being sent to the application program following a 
continuation restart might be achieved by using OS checkpoints and the CKREQ 
macro, as described below, in conjunction with ''flip-flop" files set up to revert 
upon restart to their status as of the last OS checkpoint. 

Another possibility would be to specify CKPTSYN=NO in the TPROCESS 
macros for the application program and take an OS checkpoint each time that a 
file update occurred. If one file update per message were performed and one OS 
checkpoint per message were taken, upon restart the application program would 
have to check for one duplicate message in order to ensure that updating of the 
file would resume from the point of interruption. 

Note: An OS checkpoint cannot be taken for an application program that is 
an attached task. 

In the following discussions, "system failure" is assumed to involve MCP failure. 
If the MCP fails, the application-program data sets are automatically closed; after 
the MCP is restarted, the user may restart his application program. 

Failure of the apphcation program need not be accompanied by failure of the 
MCP. In some applications, the user might wish to close down his MCP following 
abnormal termination of an application program, so that both might be restarted 
from the same point. See Coordinating MCP and Application- Program Restarts 
below for more on this topic. 

Using the CKREQ Macro Instruction for Coordination 

When a CKREQ macro is executed in an application program, a checkpoint 
request record is made in the checkpoint data set for each process queue to which 
a GET or READ macro can be directed by the application program. This record 
is used to update the MCP environment upon restart. The CKREQ macro causes 
sending to the application program after restart to begin with the last message 
marked serviced at the time the checkpoint request record was taken, rather than 
with the last message marked serviced before MCP closedown or failure. 

The CKREQ macro is effective only for queues created by TPROCESS macros 
specifying CKPTSYN=YES. When a continuation restart is performed, normal 
scanning of the message queues (as described in the discussion of the TCAM 
checkpoint facility in the chapter Using TCAM Service Facilities ) does not 
occur for message queues created by TPROCESS macros specifying 
CKPTSYN=YES. Instead, the message to be sent from the process queue to the 
application program following restart is determined by the contents of the last 
checkpoint request record made for that queue as the result of execution of a 
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CKREQ macro. If CKPTSYN=NO is specified, the first unserviced message in 
the highest-priority group of messages on the queue is sent following restart. 

When the CKREQ macro is used in an application program with low message 
traffic, the record resulting from it may be obsolete compared to the MCP envi- 
ronment (for example, it may contain information pertaining to a zone that has 
been "wrapped" on a reusable disk). When this happens, messages are lost. 

In order for the CKREQ macro to expand, a QSTART macro must be coded as 
the first macro of the appUcation program. (The QSTART macro is ordinarily 
coded only for QTAM application programs that are to run under TCAM, but is 
also coded for ordinary TCAM application programs when the CKREQ macro is 
used.) 

CKREQ has the following format: 



Name 


Operation 


Operands 


[symbol] 


CKREQ 


(no operands) 



Function: Specifies the name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

The CKREQ macro has no operands. Registers that may be altered during 
execution of the CKREQ macro are 0, 1, 14, and 15. 

Upon completion, a code is placed in register 15. Possible values are: 

X'OOOOOOOO' — checkpoint records(s) written on disk. 
X'00000004' — no checkpoint record was written on 
disk for this request. 

Suggestions for Using CKREQ: When the CKREQ macro is to be used to syn- 
chronize TCAM checkpoints of the MCP with OS checkpoints of the appHcation 
program following system failure, CKPTSYN=YES should be coded for 
TPROCESS macros creating process queues to which the application program can 
direct a GET or a READ macro. A continuation restart should be specified in the 
STARTUP= operand of the INTRO macro. 

After processing n messages or records, the user might take an OS checkpoint. 
After the OS checkpoint is taken, a CKREQ macro might be issued. If this were 
done, upon restart the application program environment would be restructured 
using the latest OS checkpoint, and a maximum of n duplicate messages (that is, 
messages already processed by the appUcation program) would be sent. 

If both OS checkpoints and checkpoint request records are used, CKREQ should 
be issued each time an OS checkpoint is taken. 

Figure 34 illustrates the use of CKREQ. 
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DESTINATION QUEUE FOR 
APPLICATION PROGRAM 



Environment 
-Checkpoint 
Record 



Message ^1 



Message ^2 



Message ^3 



Message ^4 



APPLICATION PROGRAM 





GET#1 

process and dispose of msg ^1 

OS CHECKPOINT #1 

CKREQ MACRO #1 

GET #2 

I 

process and dispose of msg ^2 

GET #3 

process and dispose of msg "^3 

I 

OS CHECKPOINT #2 

CKREQ MACRO #2 

GET #4 

process and dispose of msg ^4 



*indicates first message sent to application program from this queue following restart. 
Figure 34. Example of Using the CKREQ Macro Inslruction for Checkpoint Coordination 

A TCAM environment checkpoint record is taken before GET #1 is issued. After 
the first message is processed and disposed of by the application program, an OS 
checkpoint is taken. Upon return from the checkpoint subroutine, a checkpoint 
request record is taken of the status of the destination queue for the application 
program. When GET #2 is satisfied, (that is, after the second message has been 
moved into the work area) message #1 is marked serviced in the destination 
queue. When GET #3 is satisfied, message #2 is marked serviced. After message 
#3 is processed by the application program, another OS checkpoint record and 
TCAM checkpoint request record are taken. When GET #4 is satisfied, message 
#3 is marked serviced. 



/I, 



Assume that system failure (failure of the MCP) occurs during the processing of 
message #4. In this case, upon restart the application program would be recon- 
structed using OS checkpoint #2, and message #4 (the message pointed to by 
CKREQ macro #2) would be the first message sent upon restart. No duplication 
messages would be sent to the application program from this queue. 

Now, assume that system failure occurs during processing of message #3. In this 
case, the application-program environment would be reconstructed using OS 
checkpoint #1, and message #2 would be the first message sent upon restart. This 



< 
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would be the next unprocessed message with respect to the reconstructed 
appHcation-program environment. 

Finally, assume that system failure occurs after OS checkpoint #2 is taken, but 
before CKREQ macro #2 is executed. In this case, the application-program 
environment is reconstructed using OS checkpoint #2, but the first message sent 
upon restart is message #2. Messages #2 and #3 would be duphcate messages 
with respect to the reconstructed application-program environment. 

Using the DCB Exit for Coordination 

The input and output DCB macros for TCAM application programs permit 
specification of a user-written routine to take an OS checkpoint after each TCAM 
environment checkpoint is taken. The user may specify the address of a problem- 
program exit list by coding the EXLST= operand of the input or output DCB 
macro for the application program. The list must start on a fullword boundary; its 
format and contents are discussed in Data Management Services, The user 
specifies his OS checkpoint routine by coding an X'OF' as a control-byte in the 
exit list and following the control byte with the three-byte address of his OS 
checkpoint routine. The user routine must save and restore the contents of 
registers 1 and 14. He must not store data in the area pointed to by register 13 
upon entry to his routine. All registers except 1 and 14 contain what they held 
before the macro causing the exit to be taken is executed. In addition to coding 
the EXLST= operand of the input or output DCB macro, the user should specify 
CKPTSYN=YES in the TPROCESS macro for each process queue to which a 
GET or READ may be directed. 

When the EXLST= operand is coded, an indication is made to the application 
program each time an environment checkpoint record is made. If the EXLST= 
operand is coded in the input DCB macro, the first GET or READ macro issued 
by the application program after the environment checkpoint is taken passes 
control to the user-specified OS checkpoint routine. The GET or READ macro 
does not perform its function until after control is returned to the application 
program by the user routine. If the EXLST= operand is coded in the output DCB 
macro, the first PUT or WRITE macro issued by the apphcation program after the 
environment checkpoint is taken passes control to the user-specified OS check- 
point routine. The PUT or WRITE is honored after control is returned to the 
application program by the user routine. If OS checkpointing is used, a CKREQ 
macro should be issued after every OS checkpoint. 

Upon restart following system failure, message traffic to the application program 
resumes with the message in each process queue that was the earhest completed, 
unserviced message in the highest-priority group at the time the checkpoint was 
taken. Unserviced messages on the queue at the time the environment checkpoint 
was taken and all complete messages enqueued between the time the environment 
record was taken and the time of system failure are sent to the apphcation pro- 
gram upon restart. 

By coding the CPINTVL= operand of the INTRO macro, the user may ensure 
that environment checkpoints are taken within user-specified time limits. 

Ordinarily, the OS checkpoint routine cannot be invoked from a DCB exit routine. 
When the DCB involved is a TCAM input or output DCB, however, this restric- 
tion does not hold. 
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Coordinating MCP and Application -Program Restarts 

Information on restarting the MCP after closedown or system failure is contained 
in TCAM Checkpoint I Restart Facility in the chapter Using the TC AM Service 
Facilities . When restarting an MCP in conjunction with an appHcation program, 
the MCP is restarted first. Then the appHcation program is restarted using OS 
restart facilities. 

If the MCP terminates abnormally, any TCAM apphcation programs currently 
active are automatically terminated abnormally, providing there is at least one 
open line group in the MCP. If the TCAM checkpoint facihty is being used, a 
continuation restart may be performed for the MCP; the application program may 
then be started. 

If the application program terminates abnormally and the MCP does not termi- 
nate, the user has three courses of action open to him: 

1 . The user may restart his apphcation-program job without closing down or 
terminating the MCP job. In this case, the first message received by the 
restarted application program from a particular process queue is that unserviced 
message in the highest-priority group for that queue which was completely 
received and enqueued before any other message in the highest-priority group 
in the queue. Remember that a message is not marked serviced on disk until 
the next message to be sent to the appHcation program from the same queue 
has been transferred in its entirety to the appHcation program. Message A is 
not marked serviced until message B has been transferred to the user's work 
area. If an application close is invoked either by the CLOSE macro or by an 
abnormal termination, message B is marked serviced if it has been completely 
transferred to the application program prior to close time. Therefore, if mes- 
sage A is transferred to the appHcation program and is followed immediately by 
message B on the same process queue, and if the application program termi- 
nates abnormally when half of message B has been transferred to the applica- 
tion program, the first message to be transferred to the application program 
following its restart (assuming that the MCP continued to function between the 
time of appHcation program failure and restart) would be message B. If this 
course of action is followed, no synchronization of OS checkpoints with the 
TCAM MCP is performed. If aH of message B is transferred to the application 
program and a failure occurs during the processing of message B, message B 
win be marked serviced by the close routine activated by the abnormal termina- 
tion processing. Message B wiH not be resent if the application program is 
restarted. The message may be reprocessed by using TCAM's message retrieval 
faciHty. 

2. FoHowing failure of the appHcation program, the user can close down the 
TCAM MCP, then activate the MCP with a warm restart and the application 
program by an OS restart. In this case, the appHcation program wiH receive 
from each process queue those messages that were on the queue and unserviced 
at the time that the last checkpoint request record (or environment record, if no 
checkpoint request record was made) was taken for that queue, plus aH mes- 
sages that were placed on the queue after the last checkpoint request record 
was taken. 

3. The user may cancel his MCP job. He would then activate the MCP by using a 
continuation restart and the application program by an OS restart. In this case, 
the application program wiH receive aH messages that were on the process 
queue and unserviced at the time the last checkpoint request record (or 
environment record, if no checkpoint request record was made) was taken, plus 
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all messages that were placed on the queue after the last checkpoint request (or 
environment) record was taken. 

When reusable disk queuing is used, there is an advantage to be gained from 
combining the two coordination methods described in this section by issuing both 
a CKREQ macro and an OS checkpoint request in the DCB exit routine (see the 
chapter Z>^/mmg Data 5^/5 for a discussion of reusable disk queuing). If an 
environment checkpoint is taken due to a zone change over on the reusable-disk 
data set, checkpoint request records taken before the data set re-organization are 
now out of date, because they do not point to the zone currently being used. 
Since the DCB exit routine is given control after each environment checkpoint is 
taken, it provides the user with an opportunity to take a fresh checkpoint request 
record after each zone changeover. Only one application program and one GET 
or READ macro may refer to a process queue at any one time. 



« 

r 
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Using TCAM Service Facilities 



TCAM provides the user with a variety of faciUties that support a teleprocessing 
system. Some of these facilities are specified by the user; others are provided 
automatically by TCAM. 



Operator Control 



The operator control facility enables the user to enter operator commands to 
examine or to alter the status of a telecommunications network. Operator com- 
mands may be entered from the system console, remote stations, and application 
programs; they are supported by either resident or nonresident routines (see 
Appendix C ). A discussion of operator commands entered at the system console 
may be found in the OS pubHcation, Operator's Guide. The concepts and func- 
tions of operator commands for TCAM are discussed in TCAM Concepts and 
Facilities . 

Initialization for Operator Control 

The operator control facihty is initiaUzed through operands of the INTRO, 
TERMINAL, and TPROCESS macros. The INTRO macro specifies the single set 
of control characters to identify all operator commands (see the CONTROL= 
operand) and the primary operator control station (see the PRIMARY= oper- 
and); it also specifies the maximum number of command input blocks that may 
be used at any one time to contain operator commands entered at the system 
console (see the CIB= operand). The TERMINAL and TPROCESS macros 
associated with the stations selected as operator control stations have operands to 
indicate specification as secondary control stations (see the SECTERM= operand 
discussions of both macros). A primary operator control station receives the 
internally generated, error message, lEAOOOI, indicating that a permanent I/O 
error has occurred; it also has the capabilities of a secondary operator control 
station. (For a discussion of the lEAOOOI error message and permanent I/O 
errors, see TCAM I/O Error-Recording Facility in this chapter.) A secondary 
operator control station can send operator commands and can receive related 
responses, but not internally generated, error messages (with one exception: 
when a primary operator control station other than the system console becomes 
inoperative, message lEAOOOI is sent to the system console, in this instance a 
secondary operator control station, stating that the primary operator control 
station is inoperative). 

General Format of Operator Commands 

The fields of operator commands are separated by one or more blanks and must 
be in the order shown below. Commands entered at the system console do not 
include the control chars field and cannot occupy more than one Une (for exam- 
ple, if a command is entered through a card reader, it may not be more than 80 
characters long, and if it is typed in at the system console, it may not be longer 
than 126 characters). Commands entered from either a remote station or an 
application program must not be longer than a buffer. Required letters (those 
shown in uppercase) must be entered in uppercase when an operator command is 
entered from either a station or an appUcation program; if the command is entered 
at the system console, it may be either uppercase or lewercase. Brackets [ ] and 
braces { } are not coded. Brackets indicate an option; the enclosed item (or one 
of the several enclosed items) may be coded. Braces indicate that one of the 
several enclosed items must be coded. 

control chars operation operand [nextline] ending 
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control chars 



Used only with commands being entered either from a station or from an 
application program . Must be a character string (one to eight nonblank characters 
conforming to the rules for assembly language symbols) that identifies a command 
as an operator command (control characters are not recognized by the system if 
issued by the system console). One character string identifies all operator com- 
mands that may be entered from a station or an appUcation program and is 
specified either at assembly time by the CONTROL= operand of the INTRO 
macro or at INTRO execution time by the L= keyword response to the WTOR 
message; the character string is stored in the AVT. User- written code in the MCP 
can override the CONTROL= operand to change this character string at the 
user's discretion (see the section on user code in the chapter Designing the 
Message Handler), The control chars field must be specified except when the 
operator command is entered at the system console (in which case control chars 
must not be specified) and must be followed by one or more blanks. Command 
formats, in the Operator Commands section below, do not include the control 
chars field; however, each operator command that is entered from stations and 
application programs must begin with this character string. 



operation 



One of the following six operation types must be entered in the operation field by 
all sources requesting an operator command. One or more functions that provide 
system control are associated with each operation (see Appendix F): 

A VARY I 

r i 

.j modify! 

.JHALT 

.j display/ 

.\HOLD[ 

r \ 

.(release/ 

1^ \ 

Braces indicate that a choice must be made in the form of the command (for 
example, either VARY or V is keyed, not both; the shorter form is provided for 
coding efficiency). 






operand 



Entered by all sources requesting an operator command. This field consists of one 
or more operands (illustrated for each message in Operator Commands ). These 
operands determine which functional operator command is associated with the 
operation type specified (see Appendix F), If more than one operand is used, 
they are separated by commas without intervening blanks. 



The most common operands used by the commands are statname , address , 
grpname , and rln . 



i 
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statname 



address 



The name of the station, as specified in that station's TERMINAL macro. 

The hardware address of the hne, identical to the UNIT= operand of the DD 
statement for the line for which this operator command is being entered. 



grpname 



rln 



The name of the line group, identical to the DDNAME= operand of the DCB 
macro instruction for the line group for which the operator command is being 
entered. 



The relative hne number of the Une within the hne group. 

The first operand of all commands associated with the MODIFY operation has 
the following format: 

( [procname.]id ) 
\ jobname j 

id is the abbreviation for identifier. The [procname .] id operand is used when 
TCAM has been started; it is identical to the procname. identifier field in the 
console START command. In an MVT environment, the id suboperand is a name 
chosen by the user in the START command for entering operator commands that 
are grouped as MODIFY operations, and id alone may be coded (the use of 
procname . is optional). In an MFT environment, the id suboperand is replaced 
by the partition number. 

The jobname operand is used when TCAM is dequeued from the input stream 
(for example, from a card reader), jobname is replaced by the name of the job to 
which the MODIFY operation applies, and is identical to the jobname field in the 
job statement for the job being modified by an operator command. 

Thus, the TCAM job may be executed either as a normal job through SYSIN, or 
as a started procedure by the START command from the system console. 



[nextline]ending 



The simultaneous use of both subfields is restricted to stations entering operator 
commands (the ending subfield alone is entered when the command is from either 
the system console or an application program ). next line is replaced by the 
appropriate control characters needed to accompUsh either a carriage return or a 
new line operation to ensure that TCAM's response message does not print over 
the previous line of print. See the IBM component description SRL (for the 
device that is used to enter the operator command) to determine the correct 
control character for either a carriage return or a new hne operation. The nextline 
subfield, when used, is followed immediately, without intervening blanks, by the 
ending subfield. The [ nextline ] ending field must be separated from the operand 
field by one or more blanks; any invalid characters appearing between the blank 
delimiter and the first character of the [ nextline ] ending field are considered 
comments and are disregarded by TCAM. ending is the end-of-message signal 
and is required by all sources entering an operator command. The signal is BOB 
for the system console, EOT for start-stop stations, and ETX/EOT* for BSC 
stations. Command formats, in the Operator Commands section below, do not 
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include the [next line ] ending fields; however, each operator command that is 

entered on the Hne must contain the appropriate code as described for it above. 

/■ 

*If the CONV= operand of the STARTMH macro is specified (causing EOB, 
ETB, or ETX line-control characters to be treated like EOT Hne-control charac- 
ters), then either EOB, ETX, or ETB alone is sufficient. 

Specifying Operator Commands 

The operator commands, together with the functions they perform, are discussed 
in a later section. Specification of these commands varies sHghtly depending upon 
whether the command is entered at the system console, or from an application 
program or a remote station. 

Commands entered at the system console follow the conventions outlined in the 
Operator's Guide . Required characters (those shown in uppercase) must be 
entered, but can be entered in either uppercase or lowercase, and the console 
operator must not enter the control characters field described above. 

Commands entered either from an application program or at a remote station must 
also enter required characters, and they must be uppercase unless the translation 
table used by the CODE macro, which recognizes the command, permits lower- 
case data. Furthermore, the control characters field must be the first field entered 
for each operator command for TCAM to recognize the operation. 

Example 1: 

If TCAM has been started and the procname field of the console START com- 
mand specifies AQTPROC.QID and the INTRO macro specifies 

CONTROL=OPID, the command to change a terminal from secondary to pri- i „ 

mary operator control terminal status is: 

• From an IBM 1050 terminal 

OPID MODIFY QID , OPERATOR=NYC nextline EOT 

or 
OPID F QID , OPERATOR=NYC nextline EOT 

or 
OPID MODIFY AQTPROC . QID , OPERATOR=NYC nextline EOT 

or 
OPID F AQTPROC . QID , OPERATOR=NYC nextline EOT 

where uppercase characters are coded as shown (see the CPRIOPCL operator 
command in a later section. Operator Commands ); NYC is the name of the 
station to be made primary; nextline is replaced by the appropriate carriage-return 
operation for the 1050; and EOT is the ending character to be used with the 1050. 

• From an application program 

OPID MODIFY QID,OPERATOR=NYC EOT 

or 
OPID F QID , OPERATOR^NYC EOT 

or 

OPID MODIFY AQTPROC . QID , OPERATOR-NYC EOT 

^' I 

OPID F AQTPROC . QID , OPERATOR=NYC EOT 1 
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• From the system console 

MODIFY QID , OPERATOR=NYC BOB 

or 
F QID , OPERATOR=NYC BOB 

or 
MODIFY AQTPROC . QID , OPERATOR=NYC BOB 

or 
F AQTPROC . QID , OPERATOR=NYC BOB 

Example 2: 

If TCAM is being executed as a normal job through SYSIN with the jobname 
being TCAMJOB and the INTRO macro specifying CONTROL=OPID, the 
commands of Bxample 1 become: 

• From an IBM 1050 terminal 

OPID MODIFY TCAMJOB , OPERATOR=NYC nextline EOT 

or 
OPID F TCAMJOB, OPERATOR-NYC nextline BOT 

• From an application program 

OPID MODIFY TCAMJOB , OPERATOR^NYC BOT 

or 
OPID F TCAMJOB , OPERATOR^NYC BOT 

• From the system console 

MODIFY TCAMJOB , OPERATOR^NYC BOB 

or 
F TCAMJOB , OPERATOR=NYC BOB 

Responses to operator commands are placed on the destination queue for the 
station that entered the command, and are sent through the outgoing Message 
Handler as normal messages. If selective execution is required in the outgoing 
groups, the first outheader subgroup can use a MSGTYPB macro to detect 
operator responses and a PATH macro to vary the processing path. Since respon- 
ses to operator commands always begin with the character string IBD, they are 
easily detected by macros such as MSGTYPB. 

Operator responses are queued with no priority and without any line-control 
information. For BSC lines and lines that expect internal blocking, the 
MSGFORM macro should be issued to provide the necessary blocking. The 
operator responses are placed on the destination queue in BBCDIC and must be 
translated to line code. 

Assuming that the blocking operands and the translation table are specified in the 
DCB macro instruction for the line group of which the station accepting the 
operator response is a member, a suggested coding sequence is: 
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OUTHDR FOR OUTGOING HEADERS 

MSGTYPE C'lED' DETECT OPERATOR RESPONSES 

MSGFORM ADD BLOCKING INFORMATION 

CODE TRANSLATE TO LINE CODE 

PATH 1,PATHSW SET A PATH SWITCH 

MSGTYPE , HANDLE NON-OPERATOR RESPONSES 



OUTEND 

Possible responses to commands are included with each command description in 
the Operator Commands section. The responses described in Incorrect Messages 
(see below) may be returned in addition to one of those described for each 
command. 

Entering Operator Commands from an Application Program 

An appHcation program may enter operator commands if SECTERM= YES is 
coded in the TPROCESS macro that creates the terminal-table process entry 
associated with the PUT or WRITE macro that moves messages. 

When it wishes to enter a command, the application program moves that com- 
mand into its PUT or WRITE work area (the operator command must have the 
same format as commands that are entered from stations; the command must 
begin with the control characters field). 

A PUT or a WRITE macro is issued to move the command from the application 
program to the MCP. The inheader subgroup of the incoming group that handles 
messages entered by the application program must contain a CODE macro if the 
program may enter operator commands. One of the functions of CODE is to 
recognize operator commands (see the description of the CODE macro). Once it 
is recognized by CODE, the operator command from the appUcation program is 
treated like any other operator command. 

The response to a command entered from an application program is directed to 
the alternate destination specified by the ALTDEST= operand of the TPROCESS 
macro that creates the terminal-table process entry associated with the PUT or 
WRITE macro causing the operator command to be sent to the MCP. If no 
alternate destination is specified, the response is sent to the dead-letter queue. If 
no dead-letter queue is provided, the response is lost. 



Incorrect Messages 



The station operator may cancel a partially entered operator command by entering 
the control characters sequence (preceded and followed by one or more blanks) 
again after entering the initial control characters. When a command contains a 
character string enclosed in quotes, the quotes must be closed before entering the 
second set of control characters to cancel the first operator control command. 
At the system console, the CANCEL key is used. There is no response message 
for a canceled command. 

Incorrectly formatted commands are returned to the operator, using a WTO 
response if the system console (or card reader) is being used. The format of the 
response message to an invaUd command is: 



< 
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lED0 1 61 STATION s tatname NOT FOUND 

or 
lEDO 1 71 LINE j grpname , rln / NOTOPEN 
1 address i 

or 
lEDO 1 81 operation COMMAND INVALID 



Operator Commands 



where statname , address , grpname , and rln are explained in the operand descrip- 
tion, and operation is the operation type, as specified in the operation field and 
the first operand. 

The response IED016I is received if the station name is not in the terminal table. 
This can be caused by a misspelled name, or by a name entered in lowercase when 
a folded translation table is not used. 

IED017I is received if the line is not open, if the OPEN macro specified IDLE, if 
the groupname specified has no matching DD statement, or if the relative Une 
number specified is zero or is higher than any relative line number in the group. 

IED018I is received if the format of the command or a field in the command is 
incorrect. Possible errors include a required field missing or misspelled, fields in 
the wrong order, and numeric fields entered in non-numeric format. 



The operator commands appear in alphabetical order; command formats are 
discussed in an earher section. See the discussions of control chars and 
[ nextline ] ending in an earlier section. General Format of Operator Commands , 
to determine the appropriate control characters that must precede operator 
commands that are entered from a station or an application program, and 
carriage-return or newline control characters and the end-of-message signal to be 
used with each command. Summaries of these command functions are illustrated 
in Figure 35 at the end of this section and in Appendix F . Keyword names (for 
example, ACTVATED) are assigned to each command for ease of reference only 
(these names serve no programming function). 

Where statname appears in an operand or a response message, it refers to the 
name of a station and must be identical to the name specified for that station's 
TERMINAL macro (see the definition of symbol in the discussion of the 
TERMINAL macro). 

Likewise, grpname refers to a line group when it appears in an operand or a 
response message, and it must be identical to the name specified in the 
DDNAME= operand of the DCB macro for that line group. 

Each response message to an operator command is preceded by a message num- 
ber. The Message and Codes publication contains a sequential Hst of all TCAM 
messages, including a more complete discussion of each response to an operator 
command. 



ACTVATED 



This command requests a Ust of all entries in the invitation Ust for the specified 
line that are currently active for entering messages (see also the descriptions of the 
INACTVTD operator command and the ICOPY macro instruction for an applica- 
tion program). 
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Format: 






Control Characters 


Operation 


Operands 


control chars 


j display/ 


TP,ACT, 1 grpname,rln/ 
1 address \ 



Response: 

lEDO 1 71 LINE Wrpname , r In /noT OPEN 
iaddress i 

or 
IED036I Wrpname,rln/ACTIVE= \statname, 
/address \ JNONE 



ACTVBOTH 



Explanation: An operator command was entered to display the list of active 
stations associated with the line named by grpname,rln or address . statname,, 
are the names of the entries that meet this requirement. If there are no active 
stations on the line, statname,.,. is replaced with NONE. 



This command combines the functions of the RESMXMIT and ENTERING 
operator commands and activates a nonswitched station for both accepting and 
entering messages, or a switched Hne only for accepting messages. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


JVARVJ 


statname,ONTP,B 



statname is replaced by the name of the station to be activated. 
If a station is included more than once in an invitation list, all 
the entries for that station are activated. 

Response: 

IED016I STATION statname NOT FOUND 

or 
IED019I statname ALREADY STARTED 

Explanation: An operator command to start the station named by statname was 
entered. The station is already active. 

or 

IED020I statname STARTED 



Explanation: An operator command to start the station named statname was 
entered. The station is started, and the message is a confirmation of the action 
taken. 

or 

IED046I LINE FOR statname IS OUTPUT ONLY STATION 



i 
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Explanation: An operator command was entered to start a station for entering 
and accepting messages, statname is the name of the station to be started. The 
command is not processed. 



AUTOSTOP 



or 

IED054I statname RELEASED, SEQ-OUT=integer 

Explanation: An operator command has been entered requesting that the station 
named by statname be started for entering and accepting messages. An error 
occurred when trying to activate statname. The terminal was only released. 

or 

IED088I statname ON DIAL LINE-CANNOT BE VARIED 

Explanation: Terminals for dial lines are not in the invitation list. These terminals 
cannot be activated or deactivated, 
or 

IED090I statname IS NOT A SINGLE ENTRY 

Explanation: An operator command was entered requesting a change involving 
the line that the station named by statname is on, but statname is not a single 
entry and has no line group, relative line number, or machine address. 

or 

IED091 1 LINE FOR statname NOT OPEN 

Explanation: An operator command to start a station is received, but the line is 
not open. The requested action is not taken. 

or 

IED1 561 statname ON CONCENTRATOR-CANNOT BE VARIED 

Explanation: An operator command was entered to start a station for entering 
and accepting messages, but statname is attached to a concentrator and has no 
entries in the invitation list. The requested action cannot be performed. 

This command switches a hne from the automatic polling (Auto Poll) facility to 
the programmed polling facility, if the automatic polling bit is on in the UCBTYP 
field of the UCB for the line (if this bit is on, the user gets Auto Poll at start-up 
time). 



Format: 



Control Characters 


Operation 


Operands 


control chars 


WODIFYJ 


Uprocname.]id ) , 
nobname \ 

AUTOPOLL= \grpname,rln ,OFf/ 
) address ) 
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Response: 

IED017I LINE Wrpname,rln)NOT OPEN 



Jaddress 



or 



\ 



IED027I AUTOPOLL STOPPED FOR\grpname, rln 

/address 



Explanation: A request was made to stop automatic polling on the line named by 
grpname.rln or address . This message confirms that automatic polling has been 
stopped on this line. 

""' ( 

IED028I AUTO POLL ALREADY STOPPED FOR)grpname, rln 

/address 



AUTOSTRT 



Explanation: An operator command was entered to stop automatic polling on the 
line named by grpnamejln or address . Automatic polling on the line is not in 
progress at this time. 



or 



IED057irgrpname,rln) NOT CAPABLE OF AUTOPOLL 
\ address j 

Explanation: An operator command was entered to stop automatic poUing on the 
line named by grpname^rln or address , but according to the UCB for the line, the 
Hne is not capable of being polled automatically or is a buffered station that is 
temporarily receiving. The command is not executed. 



This command changes a Hne from the programmed polling facility to the auto- 
matic polling (Auto Poll) facility if the automatic poUing bit is on in the UCBTYP 
field of the UCB for this line. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


j modify/ 


\[procname.]id^ 
ijobname i 

AUTOPOLL= \grpname,rln/,ON 
1 address f 



Response: 

lED0 171 LINE \grpname,rln/ NOT OPEN 
i address C 
or 
IED02 1 1 AUTO POLL STARTED FOR j grpname , r In 

) address 



Explanation: A request was made to start automatic polling on the line named by 

grpname, rln or by address . This message confirms that automatic poUing has 

been started on this line. ■ 
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CPRIOPCL 



or 

IED022I AUTO POLL ALREADY STARTED FOR Jgrpname 



( address 



,rln| 



Explanation: A request was made to start automatic polling on the line named by 
grpname,rln or by address , but automatic polling is already active for the line. 



or 

IED057I 



grpname , r In / NOT CAPABLE OF AUTOPOLL 
address 



Explanation: An operator command was entered to start automatic polling on the 
line named by grpname.rln or by address , UCB for the line, the line is not capable 
of being polled automatically or is a buffered station that is temporarily receiving. 
The command is not executed. 



This command requests that either a secondary operator control station or the 
system console become the primary operator control station. 



Format: 






Control Characters 


Operation 


Operands 


control chars 


JmodifyJ 


\[procname.]id/, 
) jobname C 

OPERATOR=\statname ) 
JSYSCONJ 



statname is the name of a station other than the system console that is to become 
the primary operator control station. SYSCON must be coded if the system 
console is to become the primary operator control station. 

Response: 

IED016I STATION statname NOT FOUND 

or 
IED041 1 PRIMARY= (statname) 
JSYSCON \ 

Explanation: An operator command has been entered requesting that the station 
named by statname or the system console be made the primary operator control 
station. This message confirms that the requested action has been taken. 

or 

IED042I (SYSCON ) ALREADY PRIMARY 
(Statname) 

Explanation: An operator command has been entered requesting that the station 
named by statname or the system console be made the primary operator control 
station, but the system status indicates that this is already so. 
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or 

IED044I statname NOT ELIGIBLE FOR PRIMARY 



Explanation: An operator command was entered requesting that the station 
named by statname be made the primary operator control station, but statname is 
not eligible to be made primary (that is, it is not defined as a secondary operator 
control station). 



DATOPFLD 



This command requests that data be inserted in an option field for a station. 
Format: 



Control Characters 


Operation 


Operands 


control chars 


JMODIFYJ 


\[procname.]id/, 
/jobname ^ 

OPT=statname,opfldname,data 



statname is the name of the station whose related option field is affected by this 
operator command, opfldname is the name of the option field, as specified in its 
related OPTION macro, where data is to be inserted. The data may either be 
enclosed in C ' or X" framing characters or it may be unframed. Option fields 
defined as character format may only be modified using character format and C ' 
framing characters or hexadecimal format and X' ' framing characters. Option 
fields not defined as character format may only be modified using hexadecimal 
format and X* ' framing characters or unframed decimal integers. The largest 
decimal integer that can be specified in this command is 2147483647. 

The number of characters of data must be no greater than the size of the option 
field (if greater, the command is rejected with message IED062I). If the replace- 
ment data is shorter in length than the size defined for the field, padding is used 
according to assembler language standards. If the format of the data entered by 
the command cannot be accepted because of the definition of the format of the 
option field, the command is rejected with message IED056I. 

All OPTION names are kept in a table with their offset into the offsets field of the 
terminal entry; this enables an option field named in an operator command to be 
found. 

Response: 

IED016I STATION statname NOT FOUND 

or 

IED034I statname HAS NO opfldname OPTION 

Explanation: An operator command was entered to modify the contents of the 
option field named by opfldname for the station named by statname , but no 
option field with this name exists for this station. The command is not executed. 



or 



IED050I statname OPTION opfldname MODIFIED 



I 
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^ DEBUG 



r 






Explanation: An operator command was entered to modify the contents of the 
option field named by opfldname associated with the station named by statname . 
This message confirms that the requested action is taken. 

or 

IED056I statname OPTION opfldname DATA FORMAT INVALID 

Explanation: An operator command was entered to modify the contents of the 
option field named by opfldname associated with the station named by statname , 
but the data format specified in the command differs from the definition of the 
option field format. 

or 

IED062I statname OPTION opfldname CANNOT ACCEPT SPECIFIED DATA 

Explanation: An operator command was entered to modify the contents of the 
option field named by opfldname associated with the station named by statname , 
but the data to replace the current setting of the option field is greater in length 
than the field. 

or 

IED077I statname OPTION opfldname DATA CHARACTER INVALID 

Explanation: An operator command was entered to modify the contents of the 
option field named by opfldname associated with the station named by statname , 
but the contents of the modification data do not agree with the framing characters 
surrounding the data. 



This command activates a TCAM service aid routine that writes the dispatcher 
subtask trace table (STCB trace), the I/O interrupt trace table (line trace), or a 
trace of buffer and status information on either tape or disk. If buffers are written 
to the tape or disk data set using this command, it must be preceded by a 
GOTRACE command that activates a line trace (and the line trace requires that 
the TRACE= operand of the. INTRO macro instruction be coded). If the STCB 
trace is activated by this command, the DTRACE= operand of INTRO must 
specify a positive integer. Use of the DEBUG command requires that 
COMWRTE=YES be coded in the INTRO macro instruction. 

If either a closedown or a failure of the TCAM system occurs while DEBUG 
writing routines are still active, the functions provided by this command are not 
activated automatically when TCAM restarts. Reenter the DEBUG command 
with its appropriate operands, after TCAM restarts, to continue writing to the 
tape or disk data set. See Debugging Aids later in this chapter for more details on 
these and other diagnostic aids, including information on specifying the tape or 
disk data set and the separate utility that formats and prints the data set contents 
(the data set may contain various combinations of the STCB trace table, the I/O 
interrupt trace table, and buffers and status information). 
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Format: 



Control Characters 


Operation 


Operands 


control chars 


j modify/ 


\ [procname. ]id/,DEBUG = | L ^ 
Jjobname ^ 'D> 

(lEDQFElO) 
<IEDQFE20> 
(lEDQFE30) 



Either L or D is coded in the DEBUG = keyword operand; L causes the service 
aid routine to be loaded and activated, and D causes the service aid to be deacti- 
vated and deleted. Either lEDQFElO, IEDQFE20, or IEDQFE30 is coded as 
shown. lEDQFElO either activates (DEBUG=L) or deactivates (DEBUG=D) 
the service aid routine that writes the STCB trace table to either magnetic tape or 
disk; in order to use this service aid routine, the DTRACE= operand of the 
INTRO macro instruction must specify a nonzero value. IEDQFE20 either 
activates or deactivates the routine that writes the I/O interrupt trace table; use of 
the DEBUG command for writing the I/O interrupt trace table requires that the 
TRACE = operand of the INTRO macro instruction specify a nonzero value, and 
the GOTRACE operator command must precede the DEBUG command (to 
activate the line trace). IEDQFE30 causes either activation or deactivation of the 
service aid routine that traces TCAM buffers. See the chapter Debugging Aids 
for a description of the utility program to use to get a formatted listing of either 
the STCB trace, the line trace, or a buffer trace that is on tape or disk. 

Response: 



IED099I ROUTINE LOADED 

Explanation: The routine that was called by the DEBUG command is loaded and 
initialized. 

or 

IED1 001 ROUTINE DEACTIVATED 

Explanation: The routine designated in the DEBUG command was deactivated 
and deleted. 

or 

IED101I RESTART IN PROGRESS 

Explanation: The requested operation cannot be processed because TCAM is 
being restarted by either a checkpoint warm or a checkpoint cold restart. 



or 

IED102I INVALID OPERAND 



Explanation: The DEBUG command format is incorrect. One or more of the 
following operands were in error. 

a. A subparameter other than L or D was specified. 

b. An invalid routine name was specified. Valid names are: 



< 
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DPRIOPCL 



IEDQFE10 
IEDQFE20 
IEDQFE30 
or 
IED1 031 ROUTINE ALREADY ACTIVE 

Explanation: A request has been made to activate a debugging routine that is 
already active. 

or 

IED1 041 ROUTINE NOT ACTIVE 

Explanation: A request has been made to deactivate a debugging routine that is 
not active. 

or 

IED1 071 COMWRITE NOT ACTIVE 

Explanation: A request has been made to activate a debugging routine that 
requires that the COMWRITE routine be active. COMWRITE is not active 
(COMWRTE=YES was not specified on INTRO). 

or 

IED1 241 QUEUE HAS BEEN WRAPPED 

Explanation: The message queues data set has been wrapped. Since the message 
queues data set can no longer be formatted reUably, the lEDQXB printing utiUty 
is terminating, 
or 

IED1 251 XXX BYTES NEEDED 



This command requests the name of the current primary operator control station. 
Format: 



Control Characters 


Operation 


Operands 


control chars 


Jdisplay/ 


1P,PRITERM 



Response: 

IED041I PRIMARY=\statname 
/SYSCON 



Explanation: An operator command was entered that requested the display of the 
station that is currently the primary operator control station. This response 
displays the requested information. 



I DSECOPCL 



This command requests the names of current secondary operator control stations. 
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Format: 



ENTERING 



Control Characters 


Operation 


Operands 


control chars 


JDISPLAYJ 


TP,SECTERM 



Response: 

IED043I SECONDARY=statname, . . . 

Explanation: An operator command was entered that requested the display of all 
stations defined as secondary operator control stations, statname,... are the 
names of all stations so defined. 

All operator control stations except SYSCON are listed by this command, even if 
one of them is designated primary (a primary operator control station by defini- 
tion has the capabiUties of a secondary operator control station). However, if the 
only operator control station is the system console, statname will be replaced by 
SYSCON in the response. 



This command activates a terminal entry in an invitation hst for entering messages 
from a nonswitched station that are to be received at the central computer. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


jvARVJ 


statname,ONTP,E 



statname is replaced by the name of the station to be activated. If a station is 
included more than once in an invitation Ust, all the entries for that station are 
activated for entering messages. 

Response: 

IED016I STATION statname NOT FOUND 

or 
IED019I statname ALREADY STARTED 

Explanation: An operator command requesting the station named by statname be 
activated for entering has been received. The station is already active for enter- 
ing. 

or 

IED020I statname STARTED 



Explanation: An operator command requesting that the station named by 
statname be activated for entering has been received. This response verifies that 
the requested action has been taken. 



i 
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ERRECORD 



or 

IED046I LINE FOR statname IS OUTPUT ONLY STATION 
Explanation: An operator command requesting that the station named by 
statname be activated for entering has been received, but the station is not 
capable of entering data. The requested action is not taken. 

or 

IED088I statname ON DIAL LINE-CANNOT BE VARIED 

Explanation: Terminals for dial lines are not in the invitation Ust. These terminals 
cannot be activated or deactivated. 



or 



IED090I statname IS NOT A SINGLE ENTRY 

Explanation: An operator command was entered requesting a change involving 
the line that the station named by statname is on, but statname is not a single 
entry and has no line group, relative Une number, or machine address. 

or 

IED09 1 1 LINE FOR statname NOT OPEN 

Explanation: An operator command to start a station is received, but the line is 
not open. The requested action is not taken. 

or 

IED1 561 statname ON CONCENTRATOR- CANNOT BE VARIED 

Explanation: An operator command was entered to start a station for entering 
and accepting messages, but statname is attached to a concentrator and has no 
entries in the invitation Ust. The requested action cannot be performed. 



This command causes temporary-error records to be made for recoverable I/O 
errors occurring on a specified line or for a specified station. See the discussion of 
intensive-mode, error recording in TCAM I/O Error-Recording Facility in this 
chapter for more information on the use of the ERRECORD command. 



Format: 



Control Characters 



control chars 



Operation 



MODIFYi 

IF ' 



Operands 



[procname.Jidf, 
jobname 



INTENSE=(lINE, \grpname,rln(), 
I address 

(yERM,statname 



sense, \count/ 
15 
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grpname,rln , and address , respectively, are replaced by the name of the line group 
containing the line, the relative line number of the line within the Hne group, and 
the machine address of the line, statname is replaced by the name of the station 
for which failure incidents records are desired. Either LINE,... or TERM,... is 
coded, not both. (LINE,... provides intensive-mode, error recording for all the 
stations on the specified line; TERM,... restricts intensive-mode, error recording 
to the specified station.) sense is replaced by one of the following: 

Type of Intensive 
Sense Recording Provided 

BO busout check 

CR command reject 

DC data check 

EC equipment check 

IM general intensive mode 

IR intervention required 

LD lost data 

M2 leading graphics for 2740 Model 2 terminal 

OR overrun 

TO time-out 

UE unit exception 

Eight of the conditions Usted (busout check, command reject, data check, equip- 
ment check, intervention required, lost data, overrun, time-out) correspond to bits 
of the sense byte for the I/O device (which is, in this case, the transmission 
control unit being used). When the unit check bit is turned on in the CSW during 
an I/O operation, a sense command is issued by TCAM, and the appropriate bits 
in the sense byte are turned on. The CSW and the sense command are described 
in Principles of Operation . A detailed discussion of the meaning of each bit in 
the sense byte may be found in the component description SRL manual for the 
transmission control unit being used. 

Unit exception in the list refers to the unit exception bit of the CSW, which is 
turned on to indicate the presence of a condition that does not usually occur 
during an I/O operation. 

When M2 is coded, a temporary-error record is made when an unusual leading 
graphic character (indicating a difficulty at the terminal) is received from an IBM 
2740 Model 2 terminal, provided that the condition indicated by the character is 
recovered from. The use of leading graphic sense characters by the 2740 Model 2 
terminal to indicate the terminal status and specific error conditions, is discussed 
in the publication /i9Af 2740 Communication Terminal Models I and 2 
Component Description , Order No. GA24-3403. 

When IM is coded, a temporary-error recording is made when any of the error 
conditions in this list (except for the unusual leading graphics response for the 
IBM 2740 Model 2 terminal) occurs and is recovered from. 

The count field is replaced by a decimal number from 1 to 15 (depending upon 
the number of records desired for the incident type specified in the sense field). If 
this field is omitted, a value of 15 is assumed. 



i 
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GENPOLOFF 



Response: 

lEDO 1 61 STATION statname NOT FOUND 

or 
lED0 1 71 LINE Jgrpname , r In) NOT OPEN 
(address ) 
or 
lEDOSSI r'grpname,rln) SENSE COUNT=count, SETTING=sense 
/address 
istatname 

Explanation: An operator command is entered requesting that the sense informa- 
tion be altered for the Hne named by grpnamejln , by address , or for the station 
named by statname . This response verifies that the requested action has been 
taken. 



This command causes the invitation characters associated with the gpstatname in 
the command to be moved from the active to the inactive side of the invitation Hst. 
This same command will cause all specific poll entries having the same control unit 
address as the gpstatname entry to be moved from the inactive to the active side 
of the invitation list. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


I^RV } 


gpstatname,OFFTP, ( E ) 



gpstatname is replaced by the name of the general poll station to be deactivated. 

A general poll station is one defined by TERM=(327C or 226C) in the 
TERMINAL macro. See Specific and General Polling for the 32 70 Information 
Display System in Appendix G. 

Note: The B request will not perform a hold. 
Response: 

IED016I STATION gpstatname NOT FOUND 

Explanation: An operator command requesting the station named by gpstatname 
to be deactivated has been received and the station does not exist in the MCP. 

or 

IED144I gpstatname GENERAL POLL STOPPED 

Explanation: An operator command requesting the station named by gpstatname 
to be deactivated has been received and it is deactivated, 
or 

IED1 461 gpstatname GENERAL POLL ALREADY STOPPED 

Explanation: An operator command requesting the station named by gpstatname 
to be deactivated has been received; the station was already inactive. 
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GENPOLON 



This command cuases the invitation characters associated with the gpstatname in 
the command to be moved from the inactive to the active side of the invitation Ust. 
This same command will cause all specific poll entries having the same control unit 
address as the gpstatname entry to be moved from the active to the inactive side 
of the invitation hst. 



Format: 



Control Characters 


Operation 


Operands 


control chars 


{VARY 1 


gpstatname ,ONTP, f E ) 



gpstatname is replaced by the name of the general poll station to be activated. A 
general poll station is one defined byTERM=(327C or 226C) in the TERMI- 
NAL macro. See Specific and General PoUing for the IBM 32 70 Information 
Display System in Appendix G . 

Note: The B request will not perform a release. 
Response: 

IED016I STATION gpstatname NOT FOUND 

Explanation: An operator command requesting the station named by gpstatname 
to be activated has been received but the station does not exist in the MCP. 

IED143I gpstatname GENERAL POLL STARTED 

Explanation: An operator command requesting the station named by gpstatname 
to be activated has been received and it is activated. 

or 

IED145I gpstatname GENERAL POLL ALREADY STARTED 

Explanation: An operator command requesting the station named by gpstatname 
be activated has been received, but it was already active. 



GOTRACE 



This command activates the TCAM I/O interrupt trace facility (line I/O trace) 
for a Hne. Use of this command requires that a positive integer be specified in the 
TRACE= operand of the INTRO macro instruction. See the Debugging Aids 
section of this chapter for information on the TCAM I/O interrupt trace facility. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


WODIFYJ 


j[procname.]idf, 
/jobname ( 
i'KACE=\grpname,rln/,ON 
j address t 



i 



All OS/MFT and OS/MVT TCAM Programmer's Guide 



The trace is started for the Une specified either by grpname,rln or by address . 

Response: 

lED0 1 71 LINE\grpname , r In /NOT OPEN 
laddress I 

or 
IED023I TRACE STARTED FORigrpname , rln/ 

/address > 

Explanation: An operator command requesting that the I/O trace be started for 
the line named by grpname,rln or by address has been entered. This response 
confirms that the requested action has been taken. 

or 

IED024I TRACE ALREADY STARTED FORJgrpname , rln( 

faddress ^ 

Explanation: An operator command requesting that the I/O trace be started for 
the Une named by grpname,rln or by address has been entered, but I/O trace was 
aheady active on the Une when the command was received. 

or 

IED055I I/O TRACE CANNOT BE ALTERED 

Explanation: An operator command requesting that the I/O trace be started has 
been entered, but the trace faciUty was not defined for this execution of the 
TCAM system. 



INACTVTD 



This command requests a Ust of the inactive entries in the invitation Ust for the 
specified Une (see also the descriptions of the ACTVATED operator command 
and the ICOPY macro instruction for an application program). 



Format: 








Control Characters 


Operation 


Operands 


control chars 


JdisplayJ 


TP,INACT, 


jgrpname,rln( 
( address \ 



A Ust of inactive entries is displayed for the invitation Ust specified either by 
grpname,rln or by address. 

Response: 

IED017I LINErgrpname,rln) NOT OPEN 
(address | 
or 
IED037I (grpname^r In) INACTIVE- statname, . . . 
(address j NONE 

Explanation: An operator command has been entered requesting a display of the 
names of aU stations associated with the Une named by grpname,rln or by address 
that are currently inactive. The response provides a list of the names of aU 
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INTERVAL 



inactive stations. If no stations are inactive, NONE replaces statname,.,. in the 
response. 



This command activates the system interval whose value is specified by the 
INTVAL= operand of the INTRO macro instruction (if the INTVAL= operand is 
not coded, this operator command does not affect the system). For more informa- 
tion on the system interval, see System Interval in Defining Terminal and Line 
Control Areas, 

Format: 



Control Characters 


Operation 


Operands 


control chars 


JMODIFYJ 


Uprocname.]id/, 
nobname C 

INTERVAL=SYSTEM 



Response: 

IED01 1 1 SYSTEM INTERVAL CANNOT BE ALTERED 

Explanation: Either a system interval of zero or no system interval at all was 
specified in the INTVAL= operand of the INTRO macro or in the response to a 
WTOR message at INTRO execution time, and an operator command was entered 
to modify the value of the interval. 

or 

IED045I SYS INTERVAL ALREADY ACTIVE 



INTRCEPT 



Explanation: An operator command was entered requesting that the system 
interval be activated, but the system interval was already in the process of being 
activated. 

or 

IED093I SET SYSTEM INTERVAL COMMAND ACCEPTED 

Explanation: An operator command has entered requesting that the system 
interval be activated. This response verifies that the command has been received 
and is being acted upon. 



This command requests display of all the stations in the system that are intercept- 
ed (an intercepted station is one to which transmission has been suspended by a 
HOLD macro). 



Format: 



Control Characters 


Operation 


Operands 


control chars 


Jdisplay/ 


TP,IlMriiR 
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LNSTATUS 



Response: 

IED039I NO STATIONS INTERCEPTED 

Explanation: An operator command has been entered requesting a display of all 
intercepted stations in the TCAM system. There are no stations currently inter- 
cepted. 

or 

IED040I INTERCEPTED STATIONS=statname , . . . 

Explanation: An operator command has been entered requesting a display of the 
names of all intercepted stations in the TCAM system; statname,... are the names 
of the stations that are currently intercepted. 



This command requests display of the status field and the message error record for 
the specified line. 



Format: 






Control Characters 


Operation 


Operands 


control chars 


(DISPLAY) 


TP,LINE, ( grpname,rln) 
c address ) 



The status field and the message error record are displayed for the line specified 
either by grpnamejln or by address . 

Possible responses in the LNSTAT= field of the response message are: 

Response Meaning 

BS bisync line 

CM line in control mode 

CR continue or reset operation 

DL switched (dial) line 

IM receiving initiate-mode message 

LF line free 

MS msggen/ start-up message 

NR negative response to polling 

OC operator control is stopping line 

RC recall being performed 

RV Une in receive mode 

SD line in send mode 

TB EOT from a buffered terminal 

TR I/O trace active 

If no bits are set in the status field, the response is (NO BITS ON.) 

Possible responses in the ERR= field of the response message are given below. 
Each response is a mnemonic corresponding to a bit of the message error record. 
See Appendix B for an explanation of the error indicated by the mnemonic. If no 
bits are set in the message error record, the response is NO BITS ON . 
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ABR - abort-BSC station 

CDC - connect/disconnect error 

CHR - channel error 

CUR - control unit error 

CUT - cutoff error 

FMT - format error 

FWD - forward error 

FWD - forward error 

HDR - header incomplete 

HDW - hardware error 

INV - id from station invalid 

ISB - insufficient buffers 

LER - line error 

LST - message lost (overlaid) 

MAX - main-storage maximum passed 



MIN - main-storage minimum passed 

MNS - message not sent/received 

NOP - station inoperative 

NTS - TSO not in system 

OLT - on-Une test not in system 

ORG - invalid origin 

SEL - selection error 

SEL - selection error 

SQH - sequence high 

SQL - sequence low 

TER - terminal error 

TXT - text transfer error 

UNR - undefined error 

UNX - unit exception 

USE - user error 



For a more complete discussion of these bits and their meanings, see the TCAM 
PLM. 

Response: 



(address 



IED017I LINE (grpname,rln^ NOT OPEN 
iaddr 

[ grpname , 
(address 



or 



IED032I (grpname, rln{ LNSTAT=status , . . . ERR=error, 



Explanation: An operator command was entered requesting display of the status 
field and the message error record for the Une named by grpname, rln or by 
address . This response displays the requested information. 



,4 



NOENTRNG 



This command prevents the control program receiving messages from a specific 
nonswitched station by deactivating that station's entry in the invitation Hst. Any 
message currently being received is completed. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


Irl 


statname,OFFTP,E 



statname is replaced by the name of the nonswitched station to be stopped from 
entering messages. If a station is included more than once in an invitation Ust, all 
the entries for the station are deactivated. 

Response: 

lEDO 1 61 STATION statname NOT FOUND 

or 
IED025I statname ALREADY STOPPED 



< 
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NOTRACE 



Explanation: An operator command has been entered requesting that the station 
named by statname be stopped from entering messages. The station is already 
stopped from entering. 

or 

IED026I statname STOPPED 

Explanation: An operator command has been entered requesting that the station 
named by statname be stopped from entering messages. This response confirms 
that the requested action has been taken. 

or 

IED046I LINE FOR statname IS OUTPUT ONLY STATION 

Explanation: An operator command has been entered requesting that the station 
named by statname be stopped from entering messages, but the hne is defined as 
an output only line. The station is not capable of entering messages, and the 
requested action is not taken. 

or 

IED088I statname ON DIAL LINE-CANNOT BE VARIED 

Explanation: Terminals for dial Unes are not iii the invitation Ust. These terminals 
cannot be activated or deactivated. 

or 



/' IED090I statname IS NOT A SINGLE ENTRY 



Explanation: An operator command was entered requesting a change involving 
the line that the station named by statname is on, but statname is not a single 
entry and has no line group, relative Une number, or machine address. 

or 

IED09 1 1 LINE FOR statname NOT OPEN 

Explanation: An operator command to stop a station is received, but the Une is 
not open. The requested action is not taken. 

or 

IED1 561 statname ON CONCENTRATOR- CANNOT BE VARIED 

Explanation: An operator command was entered to start a station for entering 
and accepting messages, but statname is attached to a concentrator and has no 
entries in the invitation Ust. The requested action cannot be performed. 



This command deactivates the TCAM I/O trace facility for a line (Une trace). 
The TCAM I/O trace facility is discussed in the Debugging Aids section of this 
chapter. 
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Format: 



Control Characters 


Operation 


Operands 


control chars 


JMODIFYJ 


Uprocname.Jidf, 
|jobname C 

TRACE = { grpname,rln/,OFF 
i address ^ 



The trace is stopped for the line specified either by grpname,rln or by address . 
Response: 

IED01 71 LINE (grpname, rlnJNOT OPEN 



(address 



or 



IED029I TRACE STOPPED FOR (grpname, rlnj 

/address ' 

Explanation: An operator command has been entered requesting that I/O trace 
be stopped for the hne indicated by grpnamejln or by address . This response 
verifies that the requested action has been taken. 

or 

IED030I TRACE ALREADY STOPPED FOR (grpname, rln) 

(address ) 

Explanation: An operator command has been entered requesting that I/O trace 
be stopped for the line indicated by grpname.rln or by address , but I/O trace is 
not currently active for the line. 

or 

IED055I I/O TRACE CANNOT BE ALTERED 

Explanation: An operator command has been entered requesting that I/O trace 
be stopped, but the I/O trace facihty is not defined for this execution of the 
TCAM system. 



NOTRAFIC 



This command combines the functions of the SUSPXMIT and NOENTRNG 
operator commands and may be used to stop transmission both to and from a 
station on a nons witched hne, and to stop transmission to a station on a switched 
Hne. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


jrl 


statname,OFMP,B 



statname is replaced by the name of the station to be stopped from both accepting 
and entering messages. 



< 
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Response: 

IED016I STATION statname NOT FOUND 

or 
IED025I statname ALREADY STOPPED 

Explanation: An operator command requesting that the station named by 
statname be deactivated was entered, but the station is already inactive, 
or 

IED026I statname STOPPED 

Explanation: An operator command was entered requesting that the station 
named by statname be deactivated. This response confirms that the requested 
action has been taken. 

or 

IED046I LINE FOR statname IS OUTPUT ONLY STATION 

Explanation: An operator command was entered requesting that the station 
named by statname be deactivated, but the station is not one that is capable of 
entering and accepting messages. It may accept messages, but the line with which 
the station is associated is defined as an output-only station. The requested action 
cannot be taken. 

or 

IED05 1 1 statname SET FOR HOLD , SEQ-OUT=integer 

Explanation: An operator command has been entered requesting that the station 
named by statname be stopped from accepting and entering messages. An error 
occurred when trying to deactivate statname. The terminal was only held. 

or 

IED088I statname ON DIAL LINE-CANNOT BE VARIED 

Explanation: Terminals for dial lines are not in the invitation list. These terminals 
cannot be activated or deactivated. 

or 

IED090I statname IS NOT A SINGLE ENTRY 

Explanation: An operator command was entered requesting a change involving 
the line that the station named by statname is on, but statname is not a single 
entry and has no line group, relative line number, or machine address. 

or 

IED091 1 LINE FOR statname NOT OPEN 

Explanation: An operator command to stop a station is received, but the line is 
not open. The requested action is not taken. 

or 

IED1 561 statname ON CONCENTRATOR-CANNOT BE VARIED 
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OPTFIELD 



Explanation: An operator command was entered to start a station for entering 
and accepting messages, but statname is attached to a concentrator and lias no 
entries in the invitation Ust. The requested action cannot be performed. 



This command displays the field that is reserved in an option table by an OPTION 
macro instruction issued for a station. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


Jdisplayi 


TP,OPTION,statname,opfldname, < C > 



All OPTION names are kept in an option table with their offsets in the offsets 
field of the terminal entry; this enables an option field named in an operator 
command to be found, statname is replaced with the name of the station whose 
associated option field is to be displayed, opfldname is replaced by the name of 
the option field in the option table and is identical to the name field of the 
OPTION macro instruction that reserved space in the option table for this station. X 
is used to display any field in hexadecimal format. C is used to display a character 
field in character format. D is used to display a non-character field in decimal 
format. The largest value that can be displayed in decimal format is 2147483647. 

Leading blanks are not displayed for character fields. Leading zeros are dropped 
from the display of decimal and hexadecimal fields; however, a hexadecimal field 
whose contents are 0001 will be displayed as 01. If the field cannot be displayed 
in the format specified in the command, the command is rejected with message 
IED018I. 

Example: If the OPTION and TERMINAL macros are coded 

EX OPTION H 

TRM TERMINAL, , . . . ( OPDATA=20 ) 
the command 

D TP, OPTION, TRM, EX, D 
will cause 20 to be displayed, while the command 

D TP, OPTION, TRM, EX, X 
will cause 14 to be displayed. However, the command 

D TP, OPTION, TRM, EX, C 
will be rejected with message IED018I. 



,4 
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POLLDLAY 



Response: 

IED016I STATION statname NOT FOUND 

or 

IED034I statname HAS NO opf Idname OPTION 

Explanation: An operator command has been entered requesting the display of 
the contents of the option field named by opf Idname for the station named by 
statname , but no such option field is defined for that station. 

or 

IED035I statname OPTION opf ldname=entry 

Explanation: An operator command has been entered requesting the display of 
the contents of the option field named by opf Idname for the station named by 
statname. entry is the contents of the field, displayed in the format in which it 
was defined. 



This command, which is used only for stations on a nonswitched Une, requests a 
change in the duration of the polling delay specified for the Une group in the 
corresponding Une group DCB macro instruction. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


J modify/ 


Hprocname.]id (, 
|jobname ) 
INTERVAL=POLL,statname,data 



statname is replaced by the name of any station in the Une group, and data by the 
decimal number of seconds (not to exceed 255) to be used for the polling delay. 
The length of the polling delay is changed for the entire Une group, not just for the 
station named in the statname field above. 

Response: 

lED0 1 61 STATION statname NOT FOUND 

or 
IED048I POLLING DELAY FOR statname=data 

Explanation: An operator command has been entered requesting that the value of 
the polling delay for the station named by statname and its associated line be 
modified to the value specified by data. This reponse confirms that the requested 
action has been taken. 

or 

IED061I POLLING DELAY FOR statname CANNOT BE ALTERED 

Explanation: An operator command has been entered requesting that the value 
of the polling delay for the line associated with the station named by statname be 
modified, but the line is defined as a dial line and has no polling delay. The 
command cannot be executed. 

or 

IED091 1 LINE FOR statname NOT OPEN 
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QSTATUS 



Explanation: An operator command has been entered requesting that the value of 
the poUing delay for the line associated with the station named by statname be 
modified, but the line is not open. The command cannot be executed. 



This command requests display of the fields of a queue control block containing 
the number of messages queued, the queue status, and the priority levels permitted 
for either a line or a station queue. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


Jdisplay/ 


TP,QUEUE,statname 



If queuing is by station, statname is replaced by the name of any station for which 
the information is desired. If queuing is by line, statname may be the name of any 
station on the line for which the information is desired. 

In the response message, number specifies the number of messages in the queue. 
If the statname operand specifies the name of a TPROCESS entry and the first 
message already has been forwarded successfully to the appUcation program, the 
number displayed reflects this first message even though TCAM does not yet 
consider the message successfully sent; therefore, statname QUEUE 
SIZE=number in response IED031I will indicate a number that is one greater 
than the actual number of unsent messages. 

Possible returns for the status field are: 

SNDBUF -sending to a buffered terminal 

NONEON-no status bits on 

TWELVE -call delay is greater than twelve hours 

DELAY -in the delay queue 

BUFFRD -queue for a buffered station 

TSOSES -TSO session in progress 

RDPRIO -read has priority 

Possible returns for the queue type field in the response message are: 

DR - reusable disk queue 

DN - nonreusable disk queue 

MO - main-storage-only queue 

MR - main-storage queue with reusable disk backup 

MN - main-storage queue with nonreusable disk backup 

NO - no queuing used 



PRIORITY=integer... specifies each priority level in the LEVEL= operand of the 
TERMINAL macro instruction issued for either the station or the line (see the 
discussion of the LEVEL= operand of the TERMINAL macro). A response of 
PRIORITY=000 indicates that no priorities were specified in the TERMINAL 
macro instruction. 



i 
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RESMXMIT 



Response: 

IED01 61 STATION statname NOT FOUND 

or 
IED031I statname QUEUE 

SIZE=number,QUEUETYP=type,STATUS=status, . . . 

PRIORITY=integer, . . . 

Explanation: An operator command has been entered requesting the display of 
queue information for the station named by statname . This response displays the 
requested information. 

or 

IED090I statname IS NOT A SINGLE ENTRY 

Explanation: An operator command was entered requesting information about 
the line that the station named by statname is on, but statname is not a single 
entry and has no line group, relative line number, or machine address. 



This command releases intercepted messages queued either for a specified station 
or for the line on which the specified station is located. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


Jrelease/ 


TP= statname 



statname is replaced by the name of the station for which the released messsages 
are queued (or the name of a station on a line for which the released messages are 
queued). 

Response: 

IED016I STATION statname NOT FOUND 

or 
IED053I statname ALREADY RELEASED 

Explanation: An operator command has been entered requesting the release from 
intercept status of the station named by statname , but the station is not currently 
intercepted. 

IED054I statname RELEASED, SEQ-OUT=integer 

Explanation: An operator command has been entered requesting the release from 
intercept status of the station named by statname . This response confirms that 
the requested action has been taken, and provides the output sequence number of 
the first message to be released. 



or 



IED147I gpstatname COMMAND INVALID FOR GENERAL POLL 
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RLNSTATN 



Explanation: An operator command has been entered requesting release from 
intercept status at a general poll station. This command is invalid and is ignored. 



This command requests the relative line number on which a station resides. 
Format: 



Control Characters 


Operation 


Operands 


control chars 


^display/ 


TP,ADDR,statname 



statname is replaced by the name of the station whose relative line number is 
sought. 

Response: 

IED016I STATION statname NOT FOUND 

or 
IED038I statname IS ON LINE grpname rln address 

Explanation: An operator command was entered requesting information regard- 
ing the Une with which the station is associated, statname is the name of the 
station about which the information is requested, grpname and rln provide the 
group name and the relative Une number, and address is the hardware address of 
the line. 



STARTLINE 



IED090I statname IS NOT A SINGLE ENTRY 

Explanation: An operator command was entered requesting information regard- 
ing the line that the station named by statname is on, but statname is not a single 
entry and has no Une group, relative Une number, or machine address. 



This command causes transmission either to begin to resume on a particular Une 
(or aU the lines) in a Une group. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


in 


^(grpname,rln)|,ONl'P 
< (grpname,) > 
(address ) 



grpname is the name of the Une group and rln the relative Une number of the line 
within the Une group. The rln may also be replaced by ALL. The (grpname,rln ) 
form of the operand starts transmission on the line indicated; the (grpname, ALL) 
or the (grpname,) form starts aU the Unes in the Une group. The framing par- 
entheses must be coded if this command is entered at the system. Console address 
starts the line and is the machine address of the Une; address consists of three 
hexadecimal digits. If polling is used, an invitation Ust that is active for entering 
messages is a prerequisite for message reception. STARTLINE initiates polling, 



I 
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STATDISP 



enabling, or preparing of input lines. This command may thus be used to activate 
a line or line group that was opened idle. 

When more than one DCB is assigned the same UCB, the DCBs must have 
individual ddnames, and the VARY commands associated with these hnes must 
use the {grpnamejln ), (grpname ,ALL), or (grpname ,) format of the VARY 
command. 

Response: 

IED017I LINE(grpname,rlnJNOTOPEN 
Jaddress ' 



or 

/address 



IED019I jgrpname ,rln^ ALREADY STARTED 



Explanation: An operator command has been entered to start the line named by 
grpname, rln or by address , or the line group named by grpname (with the 
optional rln specified as ALL). The hne or Une group is already active. 



or 

J address 



IED020I jgrpname , rln /STARTED 



Explanation: An operator command has been entered to start the line named by 
grpname jln or by address or the line group named by grpname (with the optional 
rln specified as ALL). This response confirms that the requested action has been 
taken. 

IED047I SYSTEM INTERVAL IS ACTIVE 

Explanation: An operator command to start a line or line group was entered while 
the system interval was active. The command is rejected. 



or 

OLT CONTROLS LINE 

^address 



IED049I OLT CONTROLS LINE } grpname, rln / COMMAND REJECTED 

; 5 



Explanation: The operator command to start the line named by grpname,rln or 
by address has been entered, but the line is currently controlled by the on-line test 
faciUty. The command cannot be executed. 

or 

IED092I BISYNC ERROR — LINE ( grpname, rln t CANNOT BE STARTED 



! grpname, rm t < 
address ' 



Explanation: An operator command to start the line named by grpname, rln or by 
address has been entered, but it is a BSC line with an error preventing it being 
started. 



This command displays whether the Auto Poll feature is being used for a specified 
line. 
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Format: 






Control Characters 


Operation 


Operands 


control chars 


Jdisplay( 


TP,LIST, ( grpname,rln / 
i address j 



The status of the invitation hst is displayed for the line specified either by 
grpname^rln or by address. 

Response: 



(address 



IED017I LINE igrpname,rlnJNOT OPEN 
iad 

igrpname 
(address 



or 



IED059I jgrpname,rln> LIST STATUS= (AUTOPL ) 

S /nobitson! 



Explanation: An operator command requesting display of the status of the 
invitation list associated with the Hne named by grpnamejln or by address has 
been entered. This response displays the requested information. A response of 
NO BITS ON indicates an invitation Ust that is polled using programmed polUng or a 
list associated with a dial line. 



STOPLINE 



This command stops transmission of messages on a line or a line group. The last 
operand determines whether transmission stops at the end of the current message 
(C) or immediately (I). 



Format: 








Control Characters 


Operation 


Operands 


control chars 


JVARYJ 


rCgrpnamcrln)) 
<(grpname,) / 
(address ) 


,OFFTP,\c/ 



grpname is replaced by the name of the line group, and rln by the relative Hne 
number of the Une within the line group or by ALL (parentheses must be coded as 
indicated in the (grpname, rln ) or (grpname ,) form of addressing if this command 
is entered at the system console), address is replaced by the machine address of 
the line. Either C or Lis coded as shown (C stops transmission at the end of the 
current message, I stops transmission immediately). If either (grpname,rln ) or 
address is coded, transmission stops on the specified line; if (grpname ,ALL) or 
(grpname ,) is coded, transmission stops on the whole Une group. When more 
than one DCB is assigned the same UCB, the DCBs must have individual 
ddnames, and the VARY commands associated with these lines must use the 
(grpname, rln ), (grpname ,ALL), or (grpname ,) format of the VARY command. 

If a STOPLINE command is issued for a Une that is also entering an operator 
command, then that command is not considered to be an operator command and is 
sent through the Message Handler. If a STOPLINE command is issued for a Une 
that has entered an operator command that has not yet been processed, that 
command is lost. 



/I 



i 
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STSTATUS 



Response: 

IED013I STOP REQUEST FOR SELF — VARY COMMAND REJECTED 

Explanation: An operator command to stop a line was entered, but the line 
specified is that which is associated with the station that entered the command. 
The command will not be executed. 

or 

IED017I LINE (grpname,rln) NOT OPEN 
^address ) 

or 
IED025I igrpname,rln; ALREADY STOPPED 
f address ' 

Explanation: An operator command was entered to stop the line named by 
grpname,rln or by address or the line group named by grpname or by grpname , 
ALL was entered, but the line is not currently active. 

or 

IED026I Jgrpname , r In ) STOPPED 
(^address ) 

Explanation: An operator command to stop the line or line group named was 
entered. This response verifies that the requested action was taken. 

or 

IED047I SYSTEM INTERVAL IS ACTIVE 

Explanation: An operator command to stop a line or line group was entered while 
the system interval was active. The command is rejected. 

or 

IED049I OLT CONTROLS LINE ( grpname, r In ) COMMAND REJECTED 

C address ' 

Explanation: An operator command to stop the line named by grpname, rln or 
by address was entered, but the line is currently controlled by the on-Une test 
facility. The command cannot be executed. 



This command displays the station status, the input sequence number of the next 
message to be received from the station, the output sequence number of the last 
message sent to the station, and the current intensive-mode recording status. 

Format: 



Control Characters 


Operation 


Operands 


control chars 


JdisplayJ 


TP,TERM,statname 



statname is replaced by the name of the station for which the status is desired. 
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SUSPXMIT 



Response: 

lEDO 1 71 STATION statname NOT FOUND 

or 

IED033I statname STATUS=status , . . . INTENSE=jsense count) 

mo S 

IN-SEQ=integer 
OUT-SEQ=integer 

Explanation: An operator command has been entered requesting display of 
information related to the station named by statname . This response displays the 
relevant information. 

The status field in the station entry is examined, and possible conditions that may 
appear in the status,... field are: 

INTCEPT Station is intercepted. 

SCNDARY Station is a secondary operator control station. 

SNGLTRM Station entry is either a single or a group entry. 

PROCESS Station entry is a process entry. 

DISLIST Station entry is a distribution Ust. 

CASLIST Station entry is a cascade Ust. 

LINEENT Station entry is a Une entry. 

OPTFLDS Station has option fields defined. 

INTENSE = sense count indicates that a specific type {sense ) and number 
( count ) of intensive recording have been specified by the ERRECORD operator 
command for failures, where sense and count are the same as that specified in 
ERRECORD's operand fields (see ERRECORD for a description of the intensive- 
mode recordings that may be made and the restrictions on the number of record- 
ings to be made). INTENSE = NO indicates that intensive-mode recordings for 
failure incidents have not been requested by the ERRECORD command, integer 
in both IN-SEQ and OUT-SEQ refers to input and output sequence numbers, 
respectively. 



This command suspends transmission to a specified station. 
Format: 



Control Characters 


Operation 


Operands 


control chars 


JHOLDJ 


TP= statname 



The form that the suspension takes depends upon the form of the first HOLD 
macro executed following this command in the Message Handler for the station. 
If an interval is specified for HOLD, this command causes a suspension of traffic 
for that period of time (the station is said to be intercepted ). If the RELEASE 
operand is specified in the HOLD macro, suspension is maintained either until 
another operator command is issued to release messages queued for the station 
(see the RESMXMIT command), or until an MRELEASE macro (or a QTAM 
RELEASEM macro) is issued in the application program for the station. If no 
HOLD macro is specified in the MH, this command is rejected, statname is 
replaced by the name of the station to which transmission is to be suspended. 



i 
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Note: An intercepted station may still enter messages — only traffic to the station 
is suspended. 

Response: 



IED016I STATION statname NOT FOUND 

or 
IED051I statname SET FOR HOLD, SEQ-OUT=integer 

Explanation: An operator command has been entered requesting that the station 
named by statname be held. This response verifies that the requested action has 
been taken, and provides the output sequence number for the first message that is 
held. 

or 

IED052I statname ALREADY SET FOR HOLD 

Explanation: An operator command has been entered requesting that the station 
named by statname be held, but the station is already held. 

or 

IED060I statname CANNOT BE HELD 

Explanation: An operator command has been entered, requesting that the station 
named by statname be held, but the station cannot be held because it is associated 
with a main-storage-only queue, it is on a line that is not open or has been opened 
dd dummy, or there is no HOLD macro in the system. 



SYSCLOSE 



or 

IED1 471 gpstatname COMMAND INVALID FOR GENERAL POLL 

Explanation: An operator command has been entered requesting that a general 
poll station be held. This command is invalid and is ignored. 

This command initiates either a quick or a flush closedown of the system (for a 
discussion of quick and flush closedown, see the Deactivation section of the 
chapter Activation and Deactivation of the Message Control Program ). 

Format: 



Control Characters 


Operation 


Operands 


control chars 


|^T| 


TP, ("quick 1 

\flush ] 



Either QUICK or FLUSH is coded as shown (the user must determine whether he 
wants a quick or a flush closedown). 

Response: 

IED063I CLOSEDOWN IN PROGRESS — HALT COMMAND REJECTED 

Explanation: An operator command has been entered requesting that the TCAM 
system be closed down, but a closedown is already in progress. 
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or 



IED157I TCAM SYSTEM DELAY ACTIVE-HALT COMMAND REJECTED 



SYSINTVL 



Explanation: A TCAM halt command was issued while TCAM System Delay 
was active. This requested action cannot be performed. 

This command changes the duration of the system interval previously specified 
in the INTVAL= operand of the INTRO macro (if the INTVAL= operand is 
not coded, this operator command does not affect the system). 

Format: 



Control Characters 


Operation 


Operands 


control chars 


JMODIFYJ 


\[procname.]id ,( 
^jobname \ 
INTERVAL=SYSTEM,data 



For a discussion of the system interval, see The System Interval in Defining 
Terminal and Line Control Areas. 

data is replaced by the decimal number of seconds to be used for the system 
interval (65535 is the maximum number that can be specified). 

Response: 

IED011I SYSTEM INTERVAL CANNOT BE ALTERED 

Explanation: Either a system interval of zero or no system interval at all 
was specified in the INTVAL= operand of the INTRO macro or in the 
WTOR response at INTRO execution time, and an operator command was 
entered to modify the value of the interval. The interval cannot be altered. 

IED047I SYS INTERVAL IS data 

Explanation: An operator command was entered to change the system interval 
to the value specified by data. This command verifies that the action has 
been taken. 

Checkpointing Operator Commands 

If the checkpoint DCB has been opened, incident checkpoint records are 
written when the following operator commands have been successfully pro- 
cessed: 



/I 



ACTVBOTH 

AUTOSTOP 

AUTOSTRT 

CPRIOPCL 

DATOPFLD 

ENTERING 

ERRECORD 

GENPOLOFF 

GENPOLON 

GOTRACE 



NOENTRNG 

NOTRACE 

NOTRAFIC 

POLLDLAY 

RESMXMIT 

STARTLINE 

STOPLINE 

SUSPXMIT 

SYSINTVL 



Display commands and unsuccessful operations are not checkpointed. 
Commands affecting the invitation list are checkpointed only if the 
STARTUP= operand of the INTRO macro included I. 



( 
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Disk Error Handling 

The disk error handling facility enables TCAM to detect disk input/output 
errors and offers descriptive information pertaining to that error. 
Whenever a disk input /output error interruption occurs, the appropriate 
bits are examined and action is taken accordingly. In the event of 
intervention required, control is returned to the system. In case of an 
irrecoverable error abnormal termination S045 U008 will be issued. 

The following special operator awareness message is sent to the primary 
control station when a disk input/output error occurs: 

IED140I TCAM DISK ERROR aa, bbbbbbbb, 

cccccccccccccccc, ddd, ee ffffff 

aa is the event control block (ECB) completion code in decimal format. 

bbbbbbbb is the input/output block (lOB) FLAGSl , FLAGS2, SENSO, 

SENSl fields in hexadecimal format. 

cccccccccccccccc is the lOB FLAGS3 byte and channel status word (CSW) in 

hexadecimal format. 

ddd is the unit ID of the unit control block (UCB) in decimal format. 

ee is an alphabetic RD or WR denoting that the error occurred during a 

read or write operation. 

ffffff i^ the starting address of the channel program in hexadecimal format. 



TCAM I/O Error-Recovery Procedures 

The TCAM MCP indues a comprehensive set of error-recovery procedures 
for dealing with the various types of input/output errors that may occur in a 
telecommunications environment. 

Whenever an input/output error interruption occurs, the error-recovery proce- 
dures examine the sense bytes for the transmission control unit and the 
channel status work (CSW). (The CSW is described in the publication 
Principles of Operation, \Vhile the sense byte is described in the component 
description SRL for the transmission control unit being used.) 

If the CSW indicates an error condition, TCAM takes action appropriate to 
the type of error. 

An irrecoverable error is one which is incapable of being corrected by pro- 
gram action (for example, overrun on a write command). For such an error, 
TCAM sets the appropriate bit or bits in the message error record, causes 
a special operator awareness message to be sent to the primary operator control 
station, causes a permanent-error record to be written on disk by TCAM's 
I/O error-recording facility, and may cause the connection between the 
computer and the station to be terminated. 

The message error record is a five-byte storage area assigned to a message. 
The bits of the message error record indicate the presence (when on) or 
absence (when off) of specific error conditions, and may be checked by 
error-handling macros in the inmessage and oiitmessage subgroups of the 
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AREA 
AFFECTED 


TYPE OF 
FUNCTION 


KEYWORD 
NAME 


SPECIFIC 
FUNCTION 


Syst-em 




CPRIOPCL 


Changes primary operator control to another station. 






Change 


ERRECORD 
INTERVAL 
SYSINTVL 


Records recoverable and nonrecoverable failure incidents. 
Changes to system transmission interval. 
Changes the duration of the system interval. 




Closedown 


SYSCLOSE 


Initiates system closedown. 




DEBUG 


Activates a routine that dumps control blocks. 






Display 


DPRIOPCL 
DSECOPCL 
INTRCEPT 


Displays the name of the primary operator control station. 
Displays the names of all secondary operator control stations. 
Displays all intercepted stations. 




Line Grcxjp 


Change 


POLLDLAY 


Changes polling delay for a line group. 


Start 


STARTLINE 


Starts transmission on a line or a line group. 


Stop 


STOPLINE 


Stops transmission on a line or a line group. 


Line 


Change 


INTERVAL 


Changes to system transmission interval. 




ACTVATED 


Displays the names of all active stations on a line. 








INACTVTD 


Displays the names of all inactive stations on a line. 






Display 


LNSTATUS 

QSTATUS 

STATDISP 


Displays status of a communication line. 
Displays status of a message queue. 
Displays the status byte of an invitation list. 






AUTOSTRT 


Starts Auto Poll on a line. 






Start 


GOTRACE 
STARTLINE 


Starts TCAM trace facility on a line. 
Starts transmission on a line or a line group. 






AUTOSTOP 


Stops Auto Poll on a line. 






Stop 


NOTRACE 
STOPLINE 


Stops TCAM trace facility on a line. 

Stops transmission on a line or a line group. 




Station 


Activate 


ACTVBOTH 
ENTERING 


Activates a station for both accepting and entering messages. 
Activates a station for entering messages. 




Change 


CPRIOPCL 
DATOPFLD 


Changes primary operator control to another station. 
Inserts data in an option field for a station. 








ERRECORD 


Records recoverable and nonrecoverable failure incidents. 








GENPOLOFF 


Deactivates general poll. 








GENPOLON 


Activates general poll. 






ACTVATED 


Displays the names of all active stations on a line. 








DPRIOPCL 


Displays the name of the primary operator control station. 








DSECOPCL 


Displays the names of all secondary operator control stations. 








INACTVTD 


Displays the names of all inactive stations on a line. 






Display 


INTRCEPT 

OPTFIELD 

QSTATUS 

RLNSTATN 

STATDISP 

STSTATUS 


Displays the names of all intercepted stations. 
Displays an option field for a station. 
Displays the status of a message queue. 
Displays the relative line number of a station. 
Displays the status byte of an invitation list. 
Displays the status of a station. 




Resume 


RESMXMIT 


Resumes transmission to a station. 


Stop 


NOENTRNG 


Stops a station entering after current message is completed. 








NOTRAFIC 


Stops a station accepting and entering after current message is 


completed. 


Suspend 


SUSPXMIT 


Suspends transmission to a station (HOLD dependent). 



Figure 35. Operator Commands Classified by Areas Affected 
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Mid-Batch Recovery 



Message Handler. These macros perform such functions as generating error 
messages, and causing all messages queued for a station to be held on the 
queue (because, perhaps, the station is inoperative). The message error record, 
which handles text errors as well as I/O errors, is described in Appendix B. 

The TCAM I/O Error Recording Facility section of this chapter describes the 
permanent error record and the operator awareness message. Both of these yield 
information helpful to the user in diagnosing and correcting hardware difficulties 
that result in permanent I/O errors. 

The connection with the station may be terminated in one of three ways 
following an irrecoverable error. For multipoint polled stations, the computer 
polls the next station in the invitation list. For a switched station, the 
computer attempts to send the next message queued for the station; if there 
are no more messages in the queue, the computer gives the station a chance 
to enter data, then hangs up. For nonswitched contention stations, the com- 
puter merely resets itself to send or receive the next message. 

If the I/O error is not irrecoverable, TCAM's error-recovery procedures 
attempt to recover from it, usually by retransmitting the block of data for 
which the error occurred (this is called retrying the block). If the station is 
in text mode, the block probably will be retried only if at least one of these 
four operands, START=, CONT=, CONV=, LOGICAL=, of the 
STARTMH macro is coded. If none of these operands is coded, no retries 
are likely to be performed, and the error is handled as an irrecoverable 
error. (If none of these operands is coded, retries will be performed during 
receive operations for text errors if the error recovery procedures have access 
to the entire block in error.) If the station is not in text mode, the error- 
recovery procedures will retry regardless of what is coded in STARTMH. 

Two retries are performed for start-stop stations, while six are performed for 
BSC stations. If these retries fail to correct the error, it is treated as an 
irrecoverable error, and the actions described above for irrecoverable errors are 
taken. 

The user can keep track of the number of temporary errors (that is, errors 
that are recovered from as a result of retries) for a specific station by means 
of TCAM's I/O error-recording facility, described in TCAM I/O Error- 
Recording Facility below. 



TCAM allows the user to design his system to recover from permanent text 
errors encountered in any block of data following the first block in a multi- 
block message (including logical messages— see Handling Logical Messages in 
the chapter Designing the Message Handler), This capability of mid-batch 
recovery is accomplished for messages to or from a station by specifying that an 
erroneous block of text be discarded. In order for mid-batch recovery to apply for 
messages to or from a nonswitched station, the station's TERMINAL macro must 
specify MB=YES (see the description of the MB= operand on the TERMINAL 
macro); this operand need not be specified for switched or buffered stations. 

Mid-batch recovery does not apply for: 

• messages queued on main-storage-only queues; 

• messages being received in initiate mode; 
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Recovery on Input 



permanent errors encountered in the first block of text of a muitiblock message 

(in this instance, the CANCELMG and HOLD macros apply to the entire 

message); 

selection errors encountered while TCAM is performing mid-batch recovery for 

the station associated with the selection error (the CANCELMG and HOLD 

macros apply to the entire message); 

a "dropped" connection on a switched line (the CANCELMG and HOLD 

macros apply to the entire message). 



If mid-batch recovery is desired for receiving operations, STOP=YES must be 
specified on the STARTMH deUmiter macro in the incoming MH handUng 
muitiblock messages. After the normal number of retries is exhausted, an incom- 
ing block containing a permanent error is discarded by TCAM and undergoes no 
further processing once it is detected. This facility requires that the 
LEVEL =BLK operand of the CANCELMG macro be coded in the inmessage 
subgroup handUng the message (see the description of the CANCELMG macro 
elsewhere in this publication). Once the block is discarded (it is deleted from a 
message segment that has already been queued), TCAM retains the portion of the 
muitiblock message preceding the discarded portion and terminates inmessage 
processing. Normal line-scheduling procedures then go into effect; output to the 
station is withheld until TCAM completes processing on the affected incoming 
muitiblock message. (On a switched line, TCAM maintains the connection either 
until the message is entered successfully, or until a selection error occurs, or until 
the line is disconnected due to a line error.) 

For nonswitched and non-buffered stations, the MB= operand of the station's 
TERMINAL macro must specify YES. If the MB= operand is omitted, or if 
MB=NO is specified, TCAM cancels the entire incoming message. If MB = YES 
is specified, the CANCELMG macro may be included in the inmessage subgroup 
for testing whether error conditions warrant cancellation of the message. Also, 
queuing by terminal is required (see the QBY=T operand of the TERMINAL 
macro). 

If the end-of-file switch is off for a BSC station, a STX-ENQ sequence may be 
received which causes output to the station to be suspended and the text error bit 
to be set in the message error record. Output to the station is resumed (and the 
text error bit is turned off) when another record is received from the station; refer 
to the component description SRL for the BSC device being used to determine 
how to resume transmission to TCAM. 

For switched and buffered stations, the MB= operand of the TERMINAL macro 
need not be coded for mid-batch recovery (recovery is provided automatically by 
TCAM). 



Recovery on Output 



In order to include mid -batch recovery on output, the user needs to include the 
LEVEL=BLK operand on the HOLD macro and, for nonswitched stations, the 
MB= operand on the TERMINAL macro. 

Just as the input, the output side requires that the TERMINAL macro specify 
MB=YES to achieve mid-batch recovery from permanent text errors in messages 
to or from a nonswitched station. For switched and buffered stations, mid-batch 
recovery need not be specified. 
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When a permanent transmission error is detected in an outgoing multiblock 
message, the buffer containing the error is treated by TCAM as the end of the 
message and successfully transmitted. 

In order for the accepting station to actually obtain the remainder of the message 
starting with the block in error, the outmessage subgroup handUng the message 
must contain a HOLD macro specifying LEVEL =BLK (see the description of the 
HOLD macro). If the HOLD macro also specifies suspension of transmission for 
a specified period of time (see the INTVL= operand), the specified delay is 
observed before transmission to a nonswitched station is resumed (the INTVL= 
operand is ignored for switched and buffered stations during a mid-batch recovery 
operation); if the INTVL= operand is omitted, resumption of transmission is 
immediate. 

Queuing by terminal is required (see the QBY= operand of the TERMINAL 
macro instruction). 

TCAM I/O Error-Recording Facility 

TCAM provides an I/O error-recording facility that creates records on disk when 
certain terminal-related I/O errors occur. The TCAM error-recording facility, 
which is an extension of the OS/360 outboard recorder (OBR) and statistical data 
recorder (SDR) error-recording programs and operates in conjunction with 
TCAM's I/O error-recovery procedures, helps to reduce the time that the TCAM 
system is inoperative by providing information useful in diagnosing line and 
terminal problems. 

For each station for which a TERMINAL macro is issued, TCAM maintains (in 
the terminal table entry) two counters. One of these is a two-byte counter that 
keeps track of the approximate number of Start I/O (SIO) commands issued for 
the station or Hne (SIO commands issued as a result of retrying during TCAM's 
I/O error-recovery procedures are not reflected in the total count). The other is a 
one-byte counter that contains the number of temporary errors (defined errors 
occurring during SIO operations for which retry was successful) that have occur- 
red since the last error record was written on disk. If the station for which an SIO 
operation is being performed is known, the counters in the terminal table entry for 
that station are updated. The counters in a line entry in the terminal table are 
updated only if the station, for which the SIO operation is being performed, is not 
known; the counters are reset each time their contents are recorded on disk. 

Four types of I/O error records may be written on disk: permanent, temporary, 
overflow, and end-of-day. These are discussed in order in the next section. 

Kinds of TCAM I/O Error Record 

A permanent -error record is written on disk for each permanent I/O error. A 
permanent I/O error is either an irrecoverable error (that is, an undefined, 
unanticipated I/O error for which TCAM provides no error-recovery procedure), 
or an I/O error for which TCAM provides an error-recovery procedure and has 
tried several times to correct the error only to fail each time. Each permanent- 
error record contains the following information: 

• date 

• time 

I • program ID 
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station name 

type of record (permanent, temporary, overflow, end-of-day) 

contents of SIO counter for this line or station (count is approximate) 
contents of temporary-error counter for this Une or station 

first CCW 

failing CCW 

channel/unit address 

csw 

sense byte data 
device type 
unit status 
channel status 

Information on the CCW and CSW may found in the Principles of Operation . 
Record fields are discussed in the description of the IFCEREPO program in the 
Service Aids publication. 

A temporary-error record is made on disk whenever an error occurs that is speci- 
fied for a particular line or station in an ERRECORD operator command, provid- 
ed that TCAM's error-recovery procedures are successful in recovering from the 
error. If TCAM's error-recovery procedures are unsuccessful, a permanent-error 
record is made and a special message is sent to the primary operator control 
station; the contents of this message are described below. This record contains 
the same information as the permanent-error record. . More information on 
temporary-error records and their use is contained in the section, Intensive-Mode 
Error Recording. 

A counter overflow record is made when either the SIO counter or the temporary- 
error counter in a particular terminal table entry is about to overflow. This record 
consists of: 

date 

time 

program ID 

type of record 

station name 

contents of SIO counter for this station (count is approximate) 

contents of temporary-error counter for this station 

channel/unit address 

device type 

Once the record is put on disk, the counters in the terminal table entry are reset. 

When a line group data set is closed, an end-of-day record is made for each 
station and line in the Une group for which there is a terminal table entry. Each 
record contains the same information as the counter overflow record. A record is 
created only if the temporary-error counter is nonzero. 

The section below Gaining Access to I/O Error Records describes how to get 
formatted, printed records. 

Intensive-Mode Error Recording 

A station or line in intensive mode is one for which a temporary-error record is 
made each time that a specified error occurs and from which recovery is made. A 
station or line is put in intensive mode with an ERRECORD operator command. 
In issuing an ERRECORD command, the user may specify one of the particular 
types of error checked for by TCAM (time-out, lost data, overrun, data check, 
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equipment check, busout, intervention required, command reject, unit exception, 
or unusual leading graphic response from an IBM 2740 Model 2 terminal) and 
also specifies the number of times (1 to 15) that a temporary-error record is to be 
made when the specified error occurs and is recovered from for this line or station. 
Alternatively, the user may specify in the ERRECORD command that a 
temporary-error recording be made if any of the above errors (except for the 
unusual leading graphics response from the 2740 Model 2 terminal) occurs and is 
recovered from; in this case he would also specify the number of times a recording 
is to be made. 

Intensive-mode, error recording may be specified either for a line or for a station. 
If a station is specified in the ERRECORD command, temporary-error records are 
made when the error specified in the command occurs for that station and from 
which recovery is made If a line is specified, a temporary-error record is made 
each time the specified error occurs and is recovered from for any station on the 
line (that is, all stations on the Une are placed in intensive mode). 

If a station is placed in intensive mode for one type of error, and an ERRECORD 
command specifying a different type of error is then issued for the station, the 
type of error specified by the second operator command is the one that causes 
temporary-error records to be made after it is issued. An ERRECORD command 
for a Une overrides those issued previously for stations on the hne; that is, if an 
ERRECORD command, which specifies that temporary-error records be taken for 
data checks occurring for a station named NYC, is followed by an ERRECORD 
command that specifies that temporary-error records be taken for time-outs 
occurring for any station on the line, after the second command is issued 
temporary-error records will no longer be taken for data checks occurring for the 
station NYC. If a third ERRECORD command, specifying that temporary-error 
records be taken for data checks occurring for NYC, is now issued, a temporary- 
error record will be made each time a data check occurs for NYC, and each time a 
time-out condition occurs for any other station on the line. 

Operator Awareness Message 

The following message is sent to the primary operator control station when an I/O 
error occurs for which TCAM provides error-recovery procedures, if the error- 
recovery procedures are unsuccessful in correcting the error. (This message is in 
addition to the permanent-error record that is created on disk when such an error 
occurs.) 

lEAOOOI I/O ERR,aaa,bb,cccc,ddee, ffgghhhh 

aaa 

is the line address in hexadecimal format. 
bb 

is the command code in hexadecimal format as specified in the failing channel 

program. 
cccc 

is the status bytes of the channel status word (CSW), as specified in the 

input/output block (lOB), in hexadecimal format. 
dd 

is the first sense byte, as specified in the input/output block (lOB), in hexade- 
cimal format. 
ee 

always zero. 
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// 

is the TP Op code as specified in tlie failing CCW in the channel program for 
the last retry attempt (in hexadecimal format). 
gg 

is the TP Op code of the failing CCW for the first occurrence of the error. 

hhhh 

For stations on switched lines, if the station is known, hhhh is replaced by the 
last four dial digits, if assigned. For stations on nonswitched lines, hhhh is 
replaced by polling characters for receiving operations and addressing charac- 
ters for sending operations. If the station is on a switched line and is unidenti- 
fied to TCAM at the time the error occurred, hhhh is replaced by the polling 
characters for stations on this line; if no poUing characters are assigned, hhhh 
is replaced by zeros, hhhh appears in hexadecimal fofmat. 

Gaining Access to Error Records 

Permanent-error, temporary-error, counter-overflow, and end-of-day, TCAM, 
I/O error records are located in the SYSl.LOGREC data set. The user can gain 
access to these records by using the IFCEREPO service aids program; information 
on using this program to write TCAM I/O error records may be found in the 
Service Aids publication. 



Network Reconfiguration 



By Operator Commands 



Direct control of network reconfiguration during execution is available for the 
station operator and the appUcation programmer through operator commands and 
application program macros. 



Functions provided by operator commands (with the corresponding command 
name in parentheses) are: 

• starting and stopping transmission on a line or a line group (STARTLINE; 
STOPLINE); 

• starting and stopping automatic polling on a line (AUTOSTRT, AUTOSTOP); 

• starting and stopping the TCAM trace facility on a line (GOTRACE; 
NOTRACE); 

• activating and deactivating a station for accepting and/or entering messages on 
a line (ENTERING, ACTVBOTH, NOENTRNG; NOTRAFIC); 

• suspending and resuming transmission to a station (SUSPXMIT; RESMXMIT); 

• changing primary operator control to another station (CPRIOPCL); 

• activating system interval (INTERVAL); 

• changing the duration of the system interval (SYSINTVL); 

• changing the polUng delay for a line group (POLLDLAY); 

• inserting data in an option field for a station (DATOPFLD); 

• initiating system closedown (SYSCLOSE). 

An example of TCAM's flexibility provided by network reconfiguration through 
operator commands is changing the status of a defective terminal before perform- 
ing a manual, device reconfiguration. See Operator Control in an earlier section 
for further information on the use of (and for more detailed descriptions of) these 
and other operator commands. 



By Application Program Macros 



Two macros are provided for changing the contents of control blocks during 
execution of the application program; TCHNG and ICHNG are used to modify 
the contents of a terminal table entry and an invitation Ust, respectively. Two 
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TCHNG 



ICHNG 



MRELEASE 



MCPCLOSE 



Other macros, MRELEASE and MCPCLOSE, reactivate a destination and initiate 
system closedown, respectively. 



This macro, in conjunction with TCOPY, moves the contents of a terminal table 
entry to a work area (where the contents optionally may be changed), and then 
moves the modified entry back to the terminal table. Related option fields may be 
modified the same way. Execution of this macro causes an incident checkpoint to 
be taken. It includes the station status, sequence numbers, and option fields. At 
restart time if the message queues are scanned, the sequence numbers will be 
overlaid if larger sequence numbers are encountered in the messsage on the disk 
queues. 



This macro, in conjunction with ICOPY, moves the contents of a specified 
invitation list to a work area (where the contents of the invitation Ust optionally 
may be changed), and then moves the modified list contents back to the invitation 
Ust. When ICHNG executes, TCAM automatically stops message transmission on 
the line so that these changes can be made; when the invitation list contents have 
been replaced, TCAM restarts the line. Execution of the macro causes an incident 
checkpoint to be taken if I is specified in the STARTUP = operand of the INTRO 
macro. 



This macro, whose primary function is to release messages queued for a destina- 
tion, also reactivates the destination that has been inactivated by a HOLD macro 
issued in the MCP. Execution of this macro causes an incident checkpoint to be 
taken. 



This macro, when executed in a user-written termination routine, intiates close- 
down of the telecommunications system. Execution of this macro causes an 
environment checkpoint to be taken. 

For a more detailed discussion of network reconfiguration using these macros, see 
the Network Control Facilities section. See the introductory section of Writing 
Application Programs for an overview of the various approaches to incorporating 
application programs into a system (the manner in which a systems programmer 
designs his system directly affects network reconfiguration during the execution of 
his program). 

TCAM Checkpoint/Restart Facility 

The optional TCAM checkpoint/restart facility allows the TCAM system to be 
restarted with minimal loss of message data following closedown or system failure. 
TCAM achieves this goal by periodically recording, in a special data set on disk, 
information on the status of each station, destination queue, terminal table entry, 
and invitation Ust in the system; when start-up after system closedown or failure 
occurs, TCAM uses this information to restore the MCP environment to its 
condition before closedown or failure. Upon restart, the terminal table, hne, 
option table, invitation Hsts, and internal control blocks associated with stations 
and Hues are restored to the condition they were in when the last checkpoint 
record was taken; outgoing message traffic to each destination resumes with the 
highest-priority, unsent message. 
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The TCAM checkpoint/restart facility permits restoration of the MCP environ- 
ment upon restart. The OS/360 advanced checkpoint/restart facility (described 
in the Advanced Checkpoint/ Restart Planning Guide ) may be used to perform a 
similar service for TCAM application programs. In designing the TCAM facility, 
certain features were included which permit TCAM checkpoints of the MCP to be 
coordinated with OS checkpoints of TCAM application programs, so that upon 
restart the entire TCAM system (MCP plus application programs) can be restored 
as nearly as possible to its condition at the time of system closedown or failure. 
These features are discussed in the section How to Coordinate TCAM Check- 
points of the MCP with OS Checkpoints of the Application Programs of the 
chapter Writing TCAM -Compatible Application Programs. 

The check list below shows the macro instructions and operands that must be 
considered when checkpoint/restart is included in the system. 



Macro 



Operand 



Comments 



INTRO 



CPINTVL= 



J integer/ 



Specifies the maximum number of seconds between 
environment. Specify any value between 30 and 65535, 
inclusive. If this operand is omitted, CPINTVL=1800 is as- 
sumed. 



CPRCDS= 



integer ) Specifies the number of environment records to be retained in 

2 ) the checkpoint data set at any one time. Specify any value 

between 2 and 75, inclusive. If this operand is omitted, 

CPRCDS=2 is assumed. 



STARTUP= 




Specifies the type of restart to be performed following 
closedown of the MCP or system failure 



C causes a cold restart after a normal quick or flush close, and a 
continuation restart (including scanning of message queues) 
after system failure. 

CY causes a cold restart after either a quick or a flush close, or 
after a system failure. 

W causes a warm restart after a normal quick or flush close, and 
a continuation restart (including scanning of message queues) 
after system failure. 

WY causes a warm restart after either a quick or a flush close, 
and a continuation restart (without scanning the message 
queues) after system failure. 

I causes the status of each invitation Ust to be included in the 
checkpoint record (indicates whether the list is active, and if 
active, whether it is being automatically polled). This value may 
be specified only when the invitation Hst is being checkpointed. 

If this operand is omitted, a value must be specified in response 
to the WTOR message issued by INTRO at execution time. 
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Macro 



Operand 



Comments 



CKREQS= 



integer 




Specifies the maximum decimal number of destination queues in use 
at any time for application programs that include a CKREQ macro. 
integer is the number of checkpoint request records to be set up in 
a checkpoint data set. The maximum that may be specified is 255 . 
If this operand is omitted, is assumed. 



RESTART= 



integer 




Specifies the environment record used to reconstruct the MCP 
environment as it existed at the time of closedown or failure. 
causes the latest record to be used, 1 causes the next -to -the -latest 
record to be used, etc. The maximum value that may be specified 
is 255; however, the value specified must be less than the number 
of environment records kept (see the CPRCDS= operand above). 
If this operand is omitted, RESTART=0 is assumed. 



checkpoint 
DCB 



DSORG=TQ 



Identifies the data set organization as that for the message queues 
or checkpoint data set. This operand may not be omitted. 



MACRF=(G,P) 

[DDNAME=ddname] 



[OPTCD=C] 



[EXLST=address] 



Specifies that access to the data set is to be gained with GET 
and PUT macro instructions. This operand may not be omitted. 

Is the name that appears in the DD statement associated with 
the data control block. If this operand is omitted, the value 
must be provided by the user's problem program any time be- 
fore the data control block exit at open time. 

Specifies that the data set is for the checkpoint records. If this 
operand is omitted, the value must be provided either by a DD 
card, or by the user's problem program any time up to and in- 
cluding the data control block exit at open time. 

Specifies the address of the problem program exit Ust. This Hst 
must be provided if user label, data control block, or user 
ABEND exits are required. The list must start on a fullword 
boundary. The user ABEND exit is discussed in the last section 
of the chapter. Defining The MCP Data Sets . 



OPEN 



(dcbname,(INOUT)) 



An OPEN macro instruction must be provided in order to open 
the checkpoint data set. If this macro instruction is omitted, the 
checkpoint/restart facility is not activated. 



CHECKPT (none) 



When coded in an incoming group, causes an incident record to 
be made of the status and the option fields assigned to the origi- 
nating station or application program; the record is taken after 
the entire incoming group has executed. 

When coded in an outgoing group, causes an incident record to 
be made of the status and the option fields assigned to the desti- 
nation station or appHcation program; the record is taken after 
the entire outgoing group has executed. 
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Macro 



Operand 



Comments 



CKREQ 



(none) 



Coordinates TCAM checkpoints of the MCP with OS 
checkpoints of TCAM appHcation programs. When executed in 
an application program, causes a checkpoint request record to 
be made in the checkpoint data set for each process queue to 
which a GET or READ macro can be directed by the appHca- 
tion program; these records are used to update the MCP envi- 
ronment upon restart. This macro causes a message to be sent 
to the appUcation program (after restart) beginning with the last 
message sent to the application program when the checkpoint 
request record was taken, rather than beginning with the last 
message marked serviced. Expansion of the CKREQ macro 
requires that a QSTART macro be coded as the first macro in an 
application program; CKREQ is effective only for queues creat- 
ed by TPROCESS macros specifying CKPTSYN=YES. 



QSTART 



(none) 



Must be the first macro in an appUcation program that includes 
a CKREQ macro. 



TPROCESS CKPTSYN=YES 



If an OS checkpoint of the application program is used in 
synchronization with the TCAM checkpoint, CKPTSYN=YES 
must be specified in the TPROCESS macro that corresponds to 
the application program. CKPTSYN= YES specifies that the 
destination queue to which the application program directs its 
GET or READ macros is not to be purged of serviced messages 
at restart. If this operand is omitted, the queue is scanned and 
updated at restart. 



input DCB 



[EXLST=address] 



This operand must be specified if a user-written routine is to be 
given control to initiate an OS checkpoint of the appUcation 
program, address specifies the address of the problem program 
exist list; the entry in the Ust is a fullword consisting of a control 
byte (X*OF') followed by the 3-byte address of a user-written 
routine that initiates an OS checkpoint. 



output DCB [EXLST=address] 



(The discussion of the EXLST= operand for the input DCB also 
applies for the EXLST= operand of the output DCB.) 



How the TCAM Checkpoint Facility Works 

Checkpoint records containing the information necessary to reconstruct the MCP 
environment upon restart are kept in the checkpoint data set on a DASD. Direc- 
tions for defining this data set are contained in the chapter Defining the MCP 
Data Sets , while a formula for determining the amount of space to allocate for 
this data set is given below (see the section How to Get the TCAM Checkpoint 
Facility ). The four types of records that may reside in the checkpoint data set are 
a control record, two or more environment checkpoint records, a series of incident 
checkpoint records, and one or more checkpoint request records. 



Types of Checkpoint Record 



The control record is used internaUy by TCAM during restart and requires no user 
coding considerations. 
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Environment checkpoint records are used to record the total MCP environment. 
Each environment checkpoint record contains information on the status of each 
message queue, terminal, line, and (optionally) invitation hst at the time the 
record was taken, and also includes the contents of the option fields for each 
station. 

If the checkpoint/restart facility is specified, environment checkpoint records are 
taken automatically at certain points during the execution of the MCP: 

• at the beginning of execution (when the READY macro is executed); 

• when the area allotted to incident checkpoint records has been filled with data 
(see the discussion of incident checkpoint records below); 

• if a message queues data set on reusable disk is present, when a zone change- 
over occurs (see Reusable Disk Queues in the chapter Defining the MCP 
Data Sets); 

• during a quick or flush closedown (discussed in the chapter Activating and 
Deactivating the Message Control Program ) ; 

• after the time interval specified by the CPINTVL= operand of INTRO has 
expired. 

These automatic checkpoints, along with the automatic incident checkpoints 
discussed below, are sufficient to ensure satisfactory restart of the MCP itself 
after system closedown or failure. If the user is synchronizing his TCAM check- 
points with OS checkpoints of the appUcation program, he may wish to ensure that 
a TCAM environment checkpoint be taken once a certain time interval has 
elapsed since the last environment checkpoint (see the discussion of the use of the 
DCB exit for coordination in How to Coordinate TCAM Checkpoints of the 
MCP with OS Checkpoints of the Application Program in the chapter Writing 

^ TCAM 'Compatible Application Programs ). 

(.' 

This is done by specifying the time interval in the CPINTVL= operand of the 
INTRO macro instruction. TCAM keeps track of the amount of time that has 
elapsed since the last environment checkpoint; when the amount of time lapsed 
equals the time interval specified in INTRO, an environment checkpoint record is 
taken. 

The user specifies the number of environment checkpoint records he desires to 
keep in his checkpoint data set at any one time by coding the desired number in 
the CPRCDS= operand of the INTRO macro instruction. If CPRCDS=3 is 
coded, the three most recent environment checkpoint records are kept in the 
checkpoint data set. When a new checkpoint record is taken, it overlays the oldest 
environment record in the data set. Ordinarily (that is, unless the RESTART= 
operand of the INTRO macro instruction specifies some integer other than 0), 
TCAM uses the most recent environment record in the data set to reconstruct the 
MCP environment for a restart. If, however, the latest record cannot be used 
(due, perhaps to a disk Read or Write error), TCAM informs the user of this fact 
by means of a WTO message at the system console and automatically attempts to 
use the next most recent record. If that record is also unusable, and if there is 
another environment record in the data set, TCAM issues another WTO and 
attempts to use that record. 

The more environment records there are in the data set, the greater is the likeli- 
hood that the environment can be recreated for restart. However, the recreated 
environment becomes increasingly inaccurate as earUer and earher environment 
I records are used; when environment records earher than the latest are used, 

certain incident checkpoint records that TCAM needs to reconstruct the environ- 
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ment are likely to be overlaid and therefore inaccessable (see the discussion of the 
incident checkpoint below, and also the example at the end of this section). 
Another pitfall exists when a message queues data set on reusable disk is present; ( 

if TCAM's restart routine drops back to an environment checkpoint record that 
was taken so long ago that the disk containing the data set has been wrapped since 
the time the record was taken, successful restart is unlikely, since pointers used by 
the TCAM restart routine to scan the message queues will have been destroyed in 
this case (scanning is discussed below). 

Incident records are used to record single changes in terminal status, line status, 
system status, and option fields; these changes occur as a result of execution of 
MH macros, certain TCAM-related, application-program macros (TCHNG and 
ICHNG), and operator commands. Each change in station status (from active to 
inactive or vice versa) is recorded by means of an incident record if STARTUP = I 
is specified on the INTRO macro instruction at cold restart time. Each change in 
a station's option fields caused by a TCHNG macro instruction or a DATOPFLD 
operator command is automatically recorded on an incident checkpoint record. 
One incident record is made of terminal status, of sequence numbers, and of the 
contents of the option fields assigned to the origin or destination station or 
application program each time a message is processed by an incoming or outgoing 
Message Handler group containing a CHECKPT macro instruction; this record 
reflects changes in the station's option fields caused by pxocessing of the message 
by the MH. 

The user performing an initial start-up or cold restart specifies (in the 
STARTUP = operand of the INTRO macro) whether or not he wants his invita- 
tion Usts to be checkpointed. Whatever the user specifies, with respect to check- 
pointing of invitation lists, prevails until another cold restart is performed. If he 4 
specifies no checkpointing of invitation lists at initial start-up time, but asks for i| 
such checkpointing in his WTOR response at INTRO execution time during a 
warm or continuation restart, he gets no invitation-list checkpointing. If the input 
or output sequence number currently assigned to a station is less than the maxi- 
mum it has had since the last cold restart (because the counter has been changed 
by a TCHNG macro, or because the counter has ^'wrapped" from 9999 to 1), 
TCAM uses an algorithm to determine which number is restored during a warm or 
continuation restart. TCAM takes the smaller number and subtracts it from the 
larger number. If the difference is less than or equal to 5000, the larger number is 
restored; otherwise the smaller number is restored. If TCHNG changes the 
sequence number upward from that possessed by the last message, the same 
algorithm is applied to determine which number is restored. Changes in MCP 
status caused by operator commands (for example, from programmed polling to 
automatic poUing, from one polHng interval to another, from an active to an 
intercepted station) are recorded by incident checkpoints and reflected in the next 
environment record; that is, each operator command (except for INTERVAL and 
SYSCLOSE) that varies, modifies, or alters the MCP status causes incident 
records. An exception is as follows: if I is not coded in the STARTUP = operand 
of the INTRO macro, changes from active to inactive status and vice versa are not 
reflected upon start-up; the original station status, as specified in the INVLIST 
macro, is reassigned in this case. 

Incident records are used to update the information contained in environment 
records at restart time unless the STARTUP = operand of the INTRO macro 
instruction specifies WY. The TCAM restart routine takes the information ^ 

contained in the latest usable environment record (unless an integer other than « 

is coded in the RESTART = operand of the INTRO macro instruction) and 
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Scanning the Message Queues 



updates it with the contents of all incident records taken since the environment 
record was taken. 

The number of incident records that may be taken depends upon the amount of 
space allocated on the disk for the checkpoint data set (allocation is discussed 
below). When the checkpoint data set is opened, space is automatically allocated 
for the control record, the number of environment checkpoint records specified by 
the CPRCDS= operand of the INTRO macro instruction, one incident record, 
and the number of checkpoint request records specified by the CKREQS= 
operand of INTRO. Any remaining space in the data set is used to set up addition- 
al incident checkpoint records. When all the space allocated for incident check- 
point records has been filled with records, another environment checkpoint record 
is taken automatically. (For further information on incident checkpoints and how 
they interact with environment records, see the example at the end of this sec- 
tion.) 

Checkpoint request records are taken as a result of CKREQ macro instructions 
issued in an application program; they record the status of the application 
program's message queues, option fields, and sequence-number fields, and are 
used in much the same way as incident records to update the environment record 
during restart (except that the latest checkpoint request record for each 
appUcation-program queue is used to update the environment record even when 
the checkpoint request record is older than the environment record). The number 
of checkpoint request records set up by the TCAM checkpoint facility is specified 
by the CKREQS= operand of the INTRO macro instruction, and should be equal 
to the maximum number of process queues that are active at any time for applica- 
tion programs that include a CKREQ macro instruction. Each checkpoint request 
is associated with a particular process entry. Checkpoint request macro instruc- 
tions help synchronize TCAM checkpoints with OS checkpoints of the TCAM 
application programs; their use is discussed in the section How to Coordinate 
TCAM Checkpoints of the MCP with OS Checkpoints of the Application 
Program in the chapter Writing TCAM-Compatible Application Programs. 



In addition to updating the latest usable environment checkpoint record (or the 
record specified in the RESTART = operand of the INTRO macro instruction) 
with any incident records taken since the environment record, the TCAM start-up 
routine may perform a scan of the message queues in the message queues data set. 

A scan of the message queues involves searching the queues from the point at 
which the environment record being used for restart was taken to the point of 
system failure; already sent messages are passed over, so that after restart occurs, 
sending of messages to each destination station or application program represent- 
ed by a message queue resumes with the highest-priority, unsent message that was 
completely received before system failure. Scanning of the message queues occurs 
only when a restart following system failure is being performed, and then only if a 
Y is not coded in the STARTUP = operand of the INTRO macro instruction. 

When a message on a disk message queue has been completely transmitted to a 
destination station, or completely transferred by means of either GET or READ 
macro instructions to an application-program work area, a TCAM routine sets a 
special bit that marks the message on disk as serviced. For a message transmitted 
to a station, the service bit is set when acknowledgment is received from the 
station that the entire message has been successfully received. For a message sent 
to an application program, the service bit is set when TCAM satisfies either a 
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GET or a READ macro instruction for the next message in the queue; a message 
is not marked serviced until the next message has been entirely moved into the 
appHcation-program work area. In performing a scan, the TCAM restart routine 
starts with the earhest message placed on the queue (or the earliest message that 
has not been overlaid, if the queue is on reusable disk) and goes down the queue 
to the point of failure; each message with a service bit on is passed over, while 
each complete message with a service bit off is transmitted according to its 
message priority. Messages on the same destination queue and having the same 
message priority are sent on a first-ended first-out (FEFO) basis; that is, the first 
completely received message that arrived at the queue first is sent first, the second 
completely received message is sent second, etc. ' (see also the discussion of 
message priority in the chapter Defining Terminal and Line Control Areas ). 

When a scan is performed for a restart following system failure, at most one 
message per line to non-buffered stations, or per process queue for an application 
program, need be re-sent. If a message was in the proces.s of being sent to a 
station or appHcation program at the time failure occurred, that message is re-sent 
automatically if a scan is performed. If a message was in the process of being 
received from either a station or an apphcation program when failure occurred, 
that portion of the message that was received and queued before failure occurred 
is not transmitted following restart, but is lost; the message must be re-entered by 
the originating station or application program. 

When a scan is performed for buffered stations, (that is, stations for which the 
BFDELAY= operand of the TERMINAL macro is coded), at most one message 
per station , the message that was in the process of being sent or received when 
failure occurred, must be retransmitted to make sure no message is lost. 

In addition to checking the service bits and eliminating serviced messages from the 
queues, TCAM also determines whether each message was completely received at 
the time failure occurred; incomplete messages are purged from the queue and are 
not sent. 

The user may use his restart in progress routine to check the input sequence 
number in the terminal table entry for each station at the time of restart; he might 
then request, by a restart in progress message, that any message entered after the 
message having this sequence number be re-sent. (Since the input sequence 
number is not incremented until the entire message has been enqueued, this 
method will work as long as a SEQUENCE macro instruction is included in the 
inheader subgroup of the MH handling the message.) The restart in progress 
routine is described in the discussion of the READY macro instruction in the 
chapter Activating and Deactivating the Message Control Program . No restart 
in progress facility is available for appHcation programs; suggestions for rendering 
such programs relatively insensitive to system failure are contained in the section 
on coordinating TCAM and OS checkpoints in chapter Writing TCAM- 
Compatible Application Programs. 

When no scan is specified for restart following system failure (that is, if WY is 
coded in the STARTUP= operand of the INTRO macro instruction), upon restart 
those messages that were on the destination queues waiting to be sent at the time 
the environment checkpoint being used for restart was taken are sent as if they 
had been queued just after restart (that is, in FEFO order, according to priority 
groups). Messages that were on a destination queue waiting to be sent at the time 
the environment checkpoint was taken (and were subsequently sent before failure 
occurred) are re-sent following start-up. Messages that were placed on a queue 
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after the environment checkpoint was taken, and were not sent before failure 
occurred, are not sent after restart; these messages are lost. Incomplete messages 
are purged from the queues and are not sent. (Incident records are not used so 
that option fields will reflect the messages that are on each destination queue as a 
result of using the environment checkpoint record.) 

If CKPTSYN=YES is specified in a TPROCESS macro instruction, all completely 
received but unsent messages at the time the last checkpoint request record was 
made, and all messages completely received between the time the last checkpoint 
request record was made and the time of failure, are sent upon restart (unless Y is 
coded in the STARTUP = operand of the INTRO macro instruction; see the 
description of this operand). See the section on coordinating OS checkpoints with 
TCAM checkpoints in the chapter Writing TCAM-Compatible Application 
Programs for a discussion of when CKPTSYN=YES would be specified. 

Example: 

Consider a checkpoint data set that contains space for three environment check- 
point records and five incident checkpoint records. After the initial environment 
checkpoint macro executes, assume that four incident checkpoint records are 
taken. At this point, the condition of the data set can be represented as follows (if 
we ignore the control record and any checkpoint request records that may be 
present): 



Environment checkpoint records 
Incident checkpoint records 



Here, a number in the area allotted to an environment record means that the area 
has been filled with that record; a number in the area allotted to an incident 
record means that the area is filled with an incident record taken after the envi- 
ronment record having the corresponding number and before an environment 
record having a higher number. 

Assume that another incident checkpoint is taken. This causes the area allotted to 
incident records to be filled with records taken since the last environment check- 
point; as a result, a second environment record is taken in place of the next 
incident record. Now, let four more incident checkpoints be taken. These will 
overlay the earliest incident checkpoints taken after the first environment check- 
point. The data set now has the following appearance (an X over a number means 
that the record represented by that number has been overlaid): 
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Environment checkpoint records 
Incident checkpoint records 



At this point, the time interval specified in the CPINTVL= operand of the 
INTRO macro instruction expires, resulting in an environment checkpoint, which 
is followed in turn by three more incident checkpoints. The data set now has the 
following appearance: 
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Environment checkpoint records 



Incident checkpoint records 
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A zone changeover now occurs for a message queues data set on reusable disk, 
resulting in another environment record, which overlays environment record #1. 
Assume that after two more incident records are taken, system failure occurs. At 
this point, the checkpoint data set would appear as follows: 



Environment checkpoint records 
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Incident checkpoint records 



Assume that the STARTUP = operand of the INTRO macro instruction is coded 
STARTUP=W, and that the RESTART= operand is omitted. When the restart 
after failure is performed, the TCAM restart routine will attempt to reconstruct 
the environment using environment record #4 as a base. If record #4 is usable, 
the reconstructed MCP environment created through its use is updated with all the 
information contained in those incident checkpoint records for which a 4 is 
specified. 

In updating, the restart routine begins with the earUest #4 incident record, and 
proceeds from earlier to later #4 records, continuing to update until all #4 incident 
records have been used; at this point, the MCP environment created by means of 
environment record #4 i3 considered to be updated. 

After the environment record is updated, all message queues in the system are 
scanned as described above. When updating and scanning are completed, message 
traffic resumes within one message of the point of failure. 

Now, assume tliat environment record #4 is unusable, due, perhaps, to a disk I/O 
error. In this case, the user would be informed by means of a message to the 
system console that the latest environment checkpoint is unusable, and environ- 
ment record #3 would be used as the basis for restart. Environment record #3 is 
updated with all incident records that were taken after it was taken (that is, those 
labeled #3 and #4). In updating, the records still containing information related to 
incident checkpoint #3 are used first, then the two #4 records are used, starting 
with the earUer one; this sequence must be followed in order to ensure that the 
updated environment record contains the latest available information. 

If, after zone changeover, there were three #4 incident records rather than two, 
the earliest #3 record would be overlaid. 



If environment record #3 is used as the base, the reconstructed environment 
probably will not be entirely accurate. This is because the earliest #3 record in the 
incident checkpoint area has been updated for environment record #4; when this 
happened, part of the information related to environment record #3 was overlaid. 
This overlaid information may have referred to environment record fields different 
from those referred to by the data that overlaid it. The overlaid information was 
presumably superseded by the information in environment record #4, but since the 
information in environment record #4 is inaccessable, the environment record 
fields that the overlaid information pertains to may contain information that is out 
of date when restart occurs. Note that this effect is compounded if environment 
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record #3 is also unusable and record #2 is used as a base. In the present example, 
if environment record #2 were also inaccessable, the environment could not be 
reconstructed, since there are no more environment records in the data set. In this 
case, the system would be started as if no checkpoint records had been taken (that 
is, all fields would be initialized to the original values assigned at assembly time), 
and the checkpoint facility would not be available to the restarted system. The 
user would get a message at the system console informing him that his environ- 
ment was not reconstructed, and that his system has no checkpoint faciUty. To 
regain his checkpoint facility in this case, the user might close down his system, 
run the IBCDASDI utility program to assign alternates to defective tracks on the 
disk containing the checkpoint data set, and then do a cold restart. 

How to Get the TCAM Checkpoint Facility 

In order to incorporate the TCAM checkpoint faciUty into his TCAM system, the 
user must perform the following steps: 

1. Include in his MCP a DCB macro instruction defining the checkpoint data set; 

2. Include with his MCP a DD statement that allocates space on a disk for the 
checkpoint data set during initial start-up; 

3. Include in his MCP an OPEN macro instruction to open the checkpoint data 
set. 

If the user performs these steps, the TCAM checkpoint facihty is included in his 
TCAM system, where it operates automatically as described in the previous 
section. 

The DCB macro instruction and DD statement for the checkpoint data set are 
described in the chapter Defining the MCP Data Sets , while the chapter 
Activation and Deactivation contains directions for opening the checkpoint data 
set. 

Space must be allocated on disk for the checkpoint data set if the checkpoint 
facility is desired. The user specifies the number of disk tracks he needs in the 
SPACE = parameter of the DD statement for the checkpoint data set issued at 
initial MCP execution time. 

Equations that may be used to determine the number of bytes occupied by the 
checkpoint data set appear in Figure 36. The equation to be used depends upon 
whether an IBM 231 1 Disk Storage Drive, an IBM 2314 Direct- Access Storage 
Device, or an IBM 3330 Disk Storage Device is used to contain the data set. 
Formulas for converting bytes to tracks appear in the component description 
manual for the direct-access device used. 

The equations in Figure 36 are a bit complex; as an approximate figure 3 tracks on 
disk should be sufficient for checkpointing an MCP for which a total of 6 to 10 
TERMINAL and TPROCESS macros are coded. 

If insufficient storage is allocated for the checkpoint data set, the user may not get 
as much space allocated for incident records as he wants. 

For the IBM 2311 Disk Storage Drive the size in bytes of the checkpoint data set 
is given by the equation: 

S=(61 + 1.05L^ ) + 1.26AL^ +N(61-f 1.05L. ) + (M+3) (61 + 1.05^ ) 
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For the IBM 3330 Disk Storage Device, the number of bytes for a checkpoint data 
set is determined by the equation 

S=(135+L^)+N(135+L.) + (M+3)(135+^) 

For the IBM 2314 Direct Access Storage Device the size in bytes of the check- 
point data set is given by the formula 

S=(10H-1.05L^) + 1.39AL^4-N(101.05Lj) + (M+3) (lOl + l.OSL^) 

For the IBM 3330 Disk Drive the size in bytes of the checkpoint data set is given 
by the equation: 

X=(135+LJ-hN(135+LJ + (M+3)(135+LJ 
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In these equations, 

L^ =the length of a control record=30+5A 

Lg =the length of an environment record=22+BH-C4-4D+5EH- 

(21F1 +21F2 H-...+21FE) + (G(Hl +H2 +...+HJ )) 
Lj =the length of an incident record= 12+K 
h^ =the length of a checkpoint request record= 17+21F-f J 

where 

A is the value coded in the CPRCDS= operand of the INTRO macro 
instruction. 

B is the total number of bytes of data located in all option fields assigned to 
stations, Unes, or application programs. 

C is equal to the sum of the number of single entries in the terminal table 
plus the number of group entries in the terminal table. 

D is equal to the number of single, group, and process entries in the termi- 
nal table whose destination queues are maintained on disk. 

E is equal to the number of destination queues maintained on disk for 
single, group, and process entries in the terminal table. 

F is equal to the number of priority levels specified for each destination 
(assume one priority level for each destination queue defined by a 
TPROCESS macro instruction, and one for each destination queue 
defined by a TERMINAL macro instruction having no LEVEL= oper- 
and). 

G is equal to 1 if I is specified in the STARTUP= operand of the INTRO 
macro instruction; otherwise, G is equal to 0. 

H is equal to the length of an invitation list (a formula for determining this 
length is given in the discussion of the ICOPY macro instruction). 

/ is equal to the number of lines having invitation lists (not counting 
output-only lines). 

J is the length, in bytes, of the maximum number of option fields assigned 
to any one entry in the terminal table. 

K is equal to / if / is greater than 32; otherwise K is equal to 32. 

M is equal to the value coded for the CKREQS= operand of the INTRO 
macro instruction. 

N is equal to the number of incident checkpoint records desired ( N should 
be between 1 and 255). 

If Lg is less than 300 bytes, it is rounded up to 300 bytes. 

Figure 36. Equations for Determining the Size of the Checkpoint Data Set 

The Checkpoint routine uses a priority scheme to divide the space allocated for 
the checkpoint data set among the various types of checkpoint records. This is to 
ensure the most efficient use of the checkpoint facility even if less space is provid- 
ed than would be ideal. Using the available space, the checkpoint facility will: 

• reserve space for the control record; 

• reserve space for two environment records; 

• reserve space for one incident record; 

• reserve space for the number of checkpoint request records specified in the 
CKREQ= operand of the INTRO macro instruction, plus 3 (to allow for disk 
errors); 

• reserve space for an additional number of environment records sufficient to 
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bring the total number up to that specified in the CPRCDS= operand of the 
INTRO macro instruction; 
• use any remaining space to set up additional incident records. 

If there is insufficient space for items one through four, the data is not formatted, 
no checkpoint facility is provided, and an awareness message is sent to the system 
console. Also, if there is not enough main storage specified to incorporate either 
all or a part of the checkpoint/restart facility in the partition or region, the 
following awareness message is returned to the system console: 

IED009I CHECKPOINT DISK ALLOCATION ERROR — DATA SET NOT OPENED 

See the OS pubUcation Messages and Codes for explanations of and responses to 
awareness messages. 



A restart is any TCAM start-up other than the initial start-up. A restart may, but 
need not, involve reconstructing the MCP environment as it existed before system 
closedown or failure. 

The three types of restart supported by TCAM are the cold restart, the warm 
restart, and the continuation restart. These are described below. A cold restart is 
similar to the initial start-up in that the previous environment is ignored, while the 
other two types of restart both involve use of the TCAM checkpoint facility to 
reconstruct the environment as it existed before a quick or flush closedown (in the 
case of a warm restart) or system failure (in the case of a continuation restart). 

All three types of restart may be initiated by reloading the object deck for the 
assembled Message Control Program or by issuing a START command at the 
system console. For a warm restart or a continuation restart, the DISP= parame- 
ter on the DD statement for the checkpoint data set must be coded DISP=OLD; 
for a cold restart, either DISP=OLD or DISP=NEW may be coded. The chapter 
Putting the MCP Together describes the Job Control Language and procedures 
for restarting the MCP. 

A cold restart ignores the previous environment; the system is started as though 
for the first time. The message queues are considered new and must be reformat- 
ted (by the lEDQXA routine described in Appendix E ) before the restart attempt 
is made (the checkpoint data set, however, is reformatted automatically). A cold 
restart is performed when the DISP= operand of the DD statement associated 
with the checkpoint DCB macro is coded DISP=NEW. If the DD statement is 
coded DISP=OLD, a cold restart is performed following either a quick or a flush 
closedown if the STARTUP = operand of the INTRO macro instruction has a C 
coded in it, and is also performed following system failure if the STARTUP = 
operand of INTRO has CY coded in it. Finally, a cold restart is performed when 
the TCAM system fails in an attempt to perform a warm or continuation restart 
because of faulty checkpoint records; in this case, the user is informed by a 
message directed to the system console that a cold restart is being performed. (If 
none of the environment records can be read at restart time, the checkpoint data 
set is not opened, so that the ensuing restart is essentially a cold restart.) 

If the address of a good morning routine is specified in the GMMSG= operand of 
the READY macro instruction, this routine is given control immediately following 
a cold restart and before the resumption of normal message traffic. This routine, 
which is described further in the discussion of the READY macro instruction, may 
be used to provide specialized initialization for certain stations and to send a 
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message to each station in the system, informing each that a cold restart has 
occurred. 

There are two forms of restart that reconstruct the environment as it existed 
because closedown or system failure, the continuation restart and the warm 
restart. A continuation restart involves reestablishing the MCP environment as it 
existed before system failure. This is done through use of an environment record, 
incident records, and checkpoint request records in the checkpoint data set, as 
described above. A continuation restart is performed following system failure if 
the DISP= operand of the DD statement for the checkpoint data set is coded 
DISP=OLD, provided that CY is not specified in the STARTUP= operand of the 
INTRO macro instruction. 

During a continuation restart, the message queues may be scanned (as described 
in the previous section) to determine the last complete message received and 
transmitted before failure. Whether scanning is performed depends upon how the 
STARTUP= operand of the INTRO macro instruction is coded (see the descrip- 
tion of this operand). If synchronization with OS checkpoints of an application 
program is specified for a particular process queue by coding CKPTSYN= YES in 
its TPROCESS macro instruction, that queue is scanned during restart. And upon 
restart, those complete messages that were marked serviced after the last check- 
point request record was made, or that were enqueued after this record was made, 
are sent. (If no checkpoint request records were made between the time of 
start-up and the time of failure, all messages marked serviced or received since the 
last environment checkpoint record was made are sent upon restart.) 

For a warm restart following a quick or flush closedown, the MCP environment is 
reconstructed as for a continuation restart. Since an environment checkpoint is 
taken near the end of a quick or flush closedown, no incident records need be used 
to reconstruct the MCP environment during a warm restart. A warm restart is 
performed if the DISP= operand of the DD statement for the checkpoint data set 
is coded DISP=OLD, provided that a W or WY is coded in the STARTUP= 
operand of the INTRO macro instruction and that the restart follows a quick or 
flush close (both of which are described in the Deactivation section of the chapter 
Activation and Deactivation ). 

If the address of a restart in progress routine is provided in the RSMSG= oper- 
and of the READY macro instruction, this routine is given control immediately 
following a warm restart or continuation restart. This routine, which is described 
further in the discussion of the READY macro instruction, may be used to gain 
access to and to change option fields and information contained in terminal table 
entries, and may be used to inform each station that a warm or continuation 
restart has occurred. The message might also provide each station with the input 
sequence number of the last message received from the station, and request that 
all messages entered having higher sequence numbers be re-entered. 

Below is a summary of the conditions that must be met in order to obtain each of 
the types of restart described in this section. It is assumed that the DISP= 
operand of the DD statement associated with the checkpoint DCB macro instruc- 
tion is coded DISP=OLD; if DISP=NEW is coded, a cold restart is always 
performed. 
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Type of INTRO Operand Resulting 



Termination 


STARTUP= 


Restart 


Flush closedown 


WorWY 


Warm restart 


Flush closedown 


CorCY 


Cold restart 


Quick closedown 


WorWY 


Warm restart 


Quick closedown 


CorCY 


Cold restart 


System failure 


CorW 


Continuation restart with queue scan 


System failure 


WY 


Continuation restart with no queue scan 


System failure 


CY 


Cold restart 



The user may wish to specify a warm restart following a flush closedown in order 
to avoid the loss of messages that could not be flushed during closedown either 
because an application program was closed or because a station was inoperative or 
intercepted. 

Using TCAM's Message Logging Facility 

TCAM's message logging facility enables the user to keep a record of the message 
traffic handled by an MCP on a sequential data set. The LOG macro instruction 
causes either an entire incoming physical transmission (by segment), an individual 
message, or a message segment to be recorded on a log data set while the message 
is currently being processed by an MCP subgroup. 



Uses of Message Logging 



Message logging can be useful to the programmer of a telecommunications system 
in two ways: first, as an integral part of the system, recording messages for 
accounting purposes by the user, and second, as a programming aid, helping to 
diagnose errors and providing information needed to evaluate system ^^ 

performance. ^ 

Message Logging as a System Component: In some systems, it may be desirable 
for messages to be recorded for accounting purposes, even though the messages 
have been successfully dispatched to their destinations. This allows the program- 
mer greater flexibihty in his accounting procedures. Some uses of a logging 
facility might be: 

• copying groups of messages sent over a long period of time to a variety of 
destinations, 

• providing long-term back-up for messages that might be accepted by one or 
more destinations but later lost through human error, and 

• collecting exceptional cases. 

Message logging can provide any of these functions without requiring that an 
application program be written. 

Message Logging as a Programming Aid: Including a carefully designed message 
logging facility in a Message Handler permits the programmer to trace the flow of 
messages through a Message Control Program, thus allowing quick diagnosis of 
errors while debugging the MCP. By anticipating the need for debugging aids in 
the design of his message logging facility, the programmer can provide a useful 
diagnostic tool with very little programming effort. Because of its modular design, 
the message logging facility can be removed easily, without the necessity of 
rewriting any parts of the MCP involved, when the program is free of errors. 

By determining the flow patterns of message traffic, a programmer can more « 

efficiently allocate the resources of a telecommunications system. Message 
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logging assists the programmer as a data collection facility, providing the informa- 
tion needed to make such a determination. When the TCAM MCP first executes, 
it can include the code necessary to log information such as time, origin, and 
destination for each message, or in cases where traffic is heavy, for certain repre- 
sentative messages. The programmer is then able to reallocate resources efficient- 
ly, and he can easily remove the message logging facility when it is no longer 
needed. 

A later section Debugging Aids includes message logging among the various 
techniques that might be used to aid in debugging the TCAM environment. 

How Message Logging Works 

When a LOG macro executes in an MH subgroup, either an entire incoming 
physical transmission, a complete message, or a message segment is copied as it 
then exists onto a log data set. 

If logical messages have been defined for the TCAM system, the position of the 
LOG macro in the inblock subgroup determines what is to be logged by segment. 
If LOG appears before the SETEOM macro, an entire incoming transmission is 
logged. If LOG appears after SETEOM, either an individual logical message or a 
portion of a logical message is logged (see the description of the LOG macro). 

If logical messages have not been defined for the TCAM system, the operand 
coded on the LOG macro and the type of subgroup in which the LOG macro 
appears determine what is to be logged — message segment or complete message. 
If only a segment is to be logged, an operand of the LOG macro refers directly to 
the DCB for the log data set. If an entire message is to be logged, the operand 
refers to a LOGTYPE macro that points to the DCB and contains additional 
information necessary to log multiple segments. The relationship of the LOG 
macro and the various subgroups is discussed in What to Log . Figure 37 shows 
the flow of data and control that occurs during the logging process for message 
segments and complete messages. 

How to Set Up a Message Logging Facility 

This section discusses the elements of a message logging facility in the order in 
which the programmer is likely to deal with them while writing an MCP. Com- 
plete descriptions of the macro instructions discussed in this section (LOG, 
LOGTYPE, PATH, MSGTYPE, and the log DCB macros) may be found else- 
where in this publication. 

What to Log: The logging facility can handle: 

• incoming header segments, 

• incoming segments, 

• incoming messages, 

• outgoing header segments, 

• outgoing segments, and 

• outgoing messages. 

The amount of data to be logged is determined by the type of subgroup in which 
the LOG appears; if it is coded in an in block subgroup, either an entire incoming 
transmission or individual logicall messages (or portions of logical messages) are 
logged; if it is coded in an inheader or outheader subgroup, message segments that 
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Debugging Aids 



contain message headers are logged. Its occurence in an inbuffer or outbuff er 
subgroup causes each segment to be logged. Each complete message is logged 
when the LOG macro occurs in an inmessage or outmessage subgroup. 

As more data is logged, the logging facihty requires more processing time and 
main-storage space, and the logged messages occupy more space in the log data 
set. Therefore, the message logging facility should be designed to operate on the 
smallest units that will supply the information needed. In a message switching 
application, simply logging incoming headers may supply all the information that is 
needed for a logging application. In more sophisticated applications where the 
body of a message is needed, it may be necessary to log complete messages. 

The Log Data Set and its DCB: Logged messages and message segments are 
maintained on sequential data sets residing on any type of BSAM-supported 
device. There may be any number of log data sets for any given MCP. Multiple 
log data sets may be found useful where logged messages are differentiated by 
some program-discernable characteristic, such as format, destination, or source. 
The device upon which a log data set resides must be able to handle the volume of 
information expected to be logged at least as fast as the MCP can handle it. This 
prevents a backlog of messages from accumulating and being lost as buffer areas 
fill and are overwritten with new messages. Some devices that might be used for 
logging purposes are tape, disk, and, where traffic is Ught, printer. 

The DCB for a log data set is coded with the rest of the DCBs for the MCP. 
Coding details appear in the section Log Data Sets in the chapter Defining 
MCP Data Sets . Note that the size of the records is determined by the size of 
the buffer units used in the MCP. 

The LOGTYPE Macro: The LOGTYPE macro provides the additional informa- 
tion needed by a message logging facility when it is to log complete messages (that 
is, when a LOG macro appears in an inmessage or outmessage subgroup). Since 
messages consist of a series of message segments, buffer and queue areas must be 
defined; the BUFSIZE= and QUEUES= operands of the LOGTYPE macro are 
used for this purpose. When a LOGTYPE macro is needed, it should appear in 
the terminal table section of the MCP. Coding details appear in the section 
LOGTYPE in the chapter Defining Terminal and Line Control Areas. 

The LOG Macro: When the LOG macro is encountered in an MH sub- 
group, the currently processed unit is transferred to the logging medium or to a 
queue waiting for such a transfer. The operand of the macro refers either to the 
log data set or the LOGTYPE macro associated with this particular LOG macro. 
Coding details for the LOG macro are discussed in the section LOG in the 
chapter Designing the Message Handler. 

Selective Logging: It may be desirable to log only messages that meet certain 
criteria, instead of each message handled by a particular MH subgroup. Use of 
the PATH and MSGTYPE macros enables the programmer to include decision- 
making code in the message logging facility. The chapter Designing the Message 
Handler contains discussions of facilities provided by both of these macro instruc- 
tions. 



During the execution of a TCAM MCP, error messages may be directed to the 
system console and to operator control stations. Each TCAM message starts with 
an alphameric identifier; an exact definition of the message and any user action 
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that may be required is documented in alphameric order in Messages and Codes . 

When the MCP partition or region is dumped, the MCP control blocks are format- 
ted (described in the TCAMPLM), Among the blocks formatted are the terminal 
table, station control blocks, line control blocks, queue control blocks, data 
control blocks, process control blocks, and the address vector table. 



In addition to normal dumps of the MCP partition or region, TCAM provides 
some special aids for debugging the telecommunications netw^ork and the MCP. 
Two of these have already been described in this chapter; the I/O error-recording 
facility, described in the section TCAM I/O Error- Recording Procedures , and 
the TCAM logging facility, covered in the section Using TCAM's Message 
Logging Facility, A TCAM formatted ABEND dump is taken of the TCAM 
MCP partition or region that terminates abnormally; this ABEND dump, which is 
in addition to the OS ABEND dump, formats TCAM control areas and attached 
subtasks and is discussed in the TCAM User's Guide . Other optional debugging 
aids include a cross-reference table of line-related information, located in main 
storage, and special dumps of a subtask control block (STCB) trace, line I/O 
interrupt trace for a line, for buffers, and for message queues data sets. In addi- 
tion, the cross-reference table, STCB trace, and line I/O interrupt trace may 
reside in main storage and may be included in a standard dump. 

Figure 38 at the end of this section Usts coding requirements for using the special 
TCAM debugging aids, and the sections below discuss the individual aids. The 
Diagnostic Aids section of the TCAM PLM contains several tables that should 
be useful in debugging a TCAM system. 



The TCAM cross-reference table provides the user with a convenient means of 
locating in a standard OS dump certain information associated with each open 
line. The cross-reference table is built by TCAM if the user codes a nonzero 
integer in the CROSSRF= operand of the INTRO macro instruction. 

At INTRO execution time, TCAM allocates 16n-i-8 contiguous bytes of main 
storage (where n is the integer specified in the CROSSRF= operand and 8 bytes 
is the length of the control block preceding the first entry) for the cross-reference 
table, and places the address of the cross-reference table in the AVT (address 
vector table) field labeled lEDCRSRF. Each time a line is opened, the next 
available four-word entry in the cross-reference table is filled in for that Une. 
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The format of the 8-byte control block preceding the first entry is: 

Byte Explanation 

address of first available entry 

+4 address of last entry 

The format of each entry in the table is: 

Byte Explanation 

unit control block name 

+4 unit control block address 

+ 8 line control block address 

+ 12 address of a master queue control block for this line 

If queuing is by line, there is only one master queue control block assigned to the 
line, and its address is placed in the fourth word. If queuing is by terminal, there 
is a master queue control block for each station on the Une; the fourth word in this 
instance is filled in with the address of the queue control block for the station 
whose terminal-table entry appears in the terminal table before that of any other 
station on the line. (The line control block and the queue control block are 
internal TCAM control blocks and are discussed in the TCAM PLM .) If the user 
opens more lines than he provides entries for in the cross-reference table, the 
table is filled in until the space in it is exhausted; Unes opened after space runs out 
in the table have no cross-reference entries. 

TCAM Line I/O Interrupt Trace Table 

The TCAM Une I/O interrupt trace table provides a sequential record (referred to 
as a line I/O trace) in main-storage of the I/O interrupts occuring on a specified 
Une. When an I/O interrupt occurs on a line for which a Une I/O trace is request- 
ed (by the GOTRACE operator command), information about the interrupt, 
including the CSW and the CCW, is stored as an entry in the line I/O interrupt 
trace table; however, interrupts resulting from retries by TCAM's error-recovery 
procedures are not recorded. 

The Une I/O interrupt trace facility is brought into main storage by specifying a 
positive value (from 1 to 65535) in the TRACE= operand of the INTRO macro 
instruction; once it is in main storage, it may be activated and deactivated for a 
specified line by the GOTRACE and NOTRACE operator commands, respec- 
tively. 

At INTRO execution time, 32n+16 contiguous bytes of main storage (where n is 
the integer specified in the TRACE = operand and 16 bytes is the length of the 
control block preceding the first entry) are allocated for the line I/O interrupt 
trace table; TCAM places the address of the table in the lEDRACE field of the 
AVT. When aU the 32-byte entries in the I/O trace table have been fiUed, the 
earliest entries are overlaid as new interrupts occur. 

A standard OS dump, described in the Guide to Reading OS Dumps , may be 
obtained to determine the kinds of interruptions that occurred during execution of 
the MCP. 
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The format of the 16-byte control block preceding the first entry is: 
Byte Explanation 





+4 
+ 8 
+ 12 



address of current trace entry 
address of first trace entry 
address of last trace entry 
address of middle entry 



Each entry in the TCAM I/O interrupt trace table has the following format: 



Sense 
Byte 



CSW 



+1 



+8 



Interrupt CCW 



Interrupt 
CCWTP 
Op Code 



'+8 



+13 



+14 



+16 



First CCW in Channel Program Chain 



^+T( 



First 
CCWTP 
Op CODE 



+23 



+24' 



Station Name 



Channel 
and Unit 
Address 



+ 24 



+30 



+32 



The channel programs used by TCAM may be found in the TCAM PLM. A 
teleprocessing operation code (TP Op code) is assigned to each CCW, and may be 
found in the sixth byte of each CCW in the table. TP Op codes facilitate a trace 
of the channel program execution sequence — they are also described in the 
TCAM PLM . A detailed description of the contents of the sense byte may be 
found in the component description SRL publication for the transmission control 
unit being used. If the identity of the connected station is not known when the 
interrupt occurs, then the channel and unit addresses, in unpacked form, are 
placed in the last two bytes of the 32-byte entry. 

Writing on a Data Set for Later Printing 

The user invokes the I/O trace dump (IEDQFE20) by entering the DEBUG 
operator command; this routine requires that COMWRTE=YES be specified on 
the INTRO macro instruction. 

As soon as TCAM makes half the number of entries in the line I/O interrupt trace 
table that was specified on the TRACE = operand of the INTRO macro instruc- 
tion, the I/O trace dump routine passes that portion of the trace table to the 
COMWRITE routine to be written on a sequential data set (the requirements of 
COMWRITE are explained in the next section below). TCAM makes entries in 
the second half of the trace table until that section is filled, at which time the I/O 
trace dump routine again passes data to COMWRITE. TCAM continues to 
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overlay the line I/O interrupt trace table, and the process outlined above is 
repeated. 

COMWRITE Requirements and Format 

The output data set format is undefined with a maximum block size that is permis- 
sible for the particular device. An example of the JCL required to specify that the 
output data set (COMWRITE) be on tape is: 

//COMWRITE DD UNIT=2400 , DSN=COMWRITE , X 

// VOL=SER=xxxxxx,DISP=( ,KEEP) 

Multiple volumes (either labeled or unlabeled) may be specified; secondary 
allocation is not permitted. Once a disk data set is filled, the disk is wrapped with 
subsequent entries. Sample JCL for specifying that the output data set be on disk 
is: 

//COMWRITE DD UNIT^SYSDA, DSN=COMWRITE , DISP=( ,KEEP), X 
// VOL-SER=xxxxxx, SPACE=( CYL, ( 5 ) ) 

The COMWRITE data set is used also when sequentially writing the STCB trace 
and buffers (the data set is specified only once); the appropriate operand of the 
DEBUG operator command determines whether a line trace, an STCB trace, or 
buffers are written on the data set (see examples in Writing Line Trace, STCB 
Trace, and Buffers to Disk Data Set below). Output from the COMWRITE 
data set is printed by a separate task that is discussed below in COMEDIT 
Printing Utility . 

If too few entries are specified on the TRACE = operand of the INTRO macro 
instruction, COMWRITE may become too busy to forward all records to the data 
set; such records are lost and the I/O trace dump routine reuses that section of the 
table and the count field of the output indicates a missing record. When the 
printed output indicates lost records, increase the number of entries on the 
TRACE= operand of the INTRO macro to prevent reoccurrence. 

Since the blocksize is limited by the type of storage device, care must be taken in 
defining the sizes of the various main-storage trace tables to be recorded by 
COMWRITE. Since each record is one-half the trace table, no trace table can 
exceed twice the maximum blocksize permitted for the COMWRITE external 
storage device. This implies the need for tape to record extra large, main-storage 
tables since tape supports larger records than disk does. 

Dispatcher Subtask Trace Table 

The dispatcher subtask trace table is used to keep a sequential record in main 
storage of the subtasks activated by the TCAM dispatcher. An entry is placed in 
the table by the TCAM dispatcher each time a TCAM subtask is dispatched. The 
table is filled on the wraparound principle; that is, when all of the available entries 
have been used, the dispatcher places the new entries at the beginning of the table 
thus overlaying the earUest entries. The table might be used, for example, to trace 
the path of a buffer through the TCAM system. The TCAM dispatcher and 
TCAM subtasks are described in detail in the TCAM PLM . 

The dispatcher subtask trace table is generated if the user specifies some value 
between 1 and 65535 in the DTRACE= operand of the INTRO macro (see note 
below), however, at least four entries must be specified if the table is to be written 
to a COMWRITE data set. At INTRO execution time, TCAM allocates 
(16n+16) contiguous bytes of main storage (where n is the integer specified in 
the DTRACE= operand) for the table. The table consists of a 16-byte control 
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block followed by n 16-byte entries. The address of the 16-byte control block is 
then stored in a field in the AVT (address vector table) at a displacement of 12 
bytes past the label lEDPARM. 

The control block for the dispatcher subtask trace table has the following format: 

Byte Explanation 

address of next entry to appear in the table 

+4 address of first entry in the table 

+ 8 address of last entry in the table 

+ 12 size of the table in bytes 

Since the first word of this control block contains the address of the next entry in 
the table, the last recorded entry is located at this address minus 16. 

An entry in the dispatcher subtask trace table has the following format: 

-I 



priority of the 
dispatched element 



address of the 
dispatched element 



+ 1 




address of the 
entry point of the 
dispatched subtask 



+4 



flag byte of the 
dispatched QCB 



address of the 
dispatched QCB 



+8 



+ 9 



subtask entry 
code (MCPL) 



address of the 
dispatched STCB 



+ 12 



+ 13 




For a further description of the QCB, the QCB flag byte, the STCB, the subtask 
entry code (MCPL) and the priority of the dispatched element, refer to the 
TCAM PLM. 

The subtask trace, like the line trace, can be written sequentially to a data set 
(either magnetic tape or disk) provided the COMWRTE= operand of the INTRO 
macro instruction specifies YES. See the DEBUG operator command for a 
description of how to activate and deactivate the STCB trace (lEDQFElO). The 
requirements of COMWRITE are discussed earUer in COMWRITE Require- 
ments and Format. 

The user codes the DTRACE= operand of the INTRO macro to determine the 
number of entries to be made in the dispatcher trace table; as soon as TCAM has 
made half the specified number of entries, lEDQFElO determines that new entries 
exist in the first half of the table and passes the first half of the trace table to 
COMWRITE to be written on a sequential data set. TCAM continues, without 
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Buffer Trace 



interruption, filling in the last half of the table with entries. When the second half 
is filled, lEDQFElO passes the second half to COMWRITE to be written. Each 
time lEDQFElO is entered, a counter is incremented and placed in the output 
record. 

If too few entries are specified on the DTRACE= operand of the INTRO macro 
instruction, COMWRITE may become too busy to forward all records to the data 
set; such records are lost and lEDQFElO reuses that section of the table and the 
count field of the output indicates a missing record. When the printed output 
indicates lost records, increase the number of entries on the DTRACE= operand 
of INTRO to prevent reoccurrence. 

Since the blocksize is limited by the type of storage device, care must be taken in 
defining the sizes of the various main-storage trace tables to be recorded by 
COMWRITE. Since each record is one half the trace table, no trace table can 
exceed twice the maximum blocksize permitted for the COMWRITE external 
storage device. This implies the need for tape to record extra large, main-storage 
tables. 



This facility permits TCAM buffer contents and status information to be dumped 
to a data set residing either on magnetic tape or on disk. To get this facility, the 
user specifies YES on the COMWRTE= operand of the INTRO macro instruction 
(causing a routine to be attached to the TCAM partition or region that sequential- 
ly writes buffers to tape or disk), and enters the DEBUG operator command to 
activate IEDQFE30. The data set to which buffers are written is specified by the 
JCL that is discussed above in COMWRITE Requirements and Format . The 
buffer trace also requires that a line trace be active on the line whose buffers are 
to be dumped (see I/O Interrupt Trace Table , covered earlier in this section, for 
a discussion of how to activate the line trace). 

The format of the buffer trace on tape or disk is: 



Buffer 
Address 



SCB Error 
Flags 







+4 



lOB 
FLl 



lOB 
FL3 



ERB 

Status 




CSW 



Sense 
Byte 



+ 12 



+ 13 



Line 
Address 



Buffer Prefix 
and Data 



+ 13 



■14 



+ 15 



+ 16 



+ 18 



+20 



+ 96 



See a later section, COMEDIT Printing Utility for a discussion of how the 
COMEDIT routine can produce a formatted Hsting of the buffer dump. 



Writing Line Trace, STCB Trace, and Buffers to Disk Data Set 

The following example of entering GOTRACE, NOTRACE, and DEBUG 
operator commands illustrates how debugging information can be written to the 
COMWRITE data set for later printing. The general format of the commands and 
command responses used in the example may be found in this chapter under the 
heading Operator Commands . The numbered paragraphs below denote a se- 
quence of operator commands entered at an IBM 1050 Data Communication 
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System terminal that has been designated as an operator control station. The 
lettered entries designate discussions of 

A. STCB trace 

B. line I/O trace 

C. buffer dump 

The example assumes that the INTRO macro instruction specifies 
COMWRTE=YES, DTRACE= integer, TRACE = integer, and 
CONTROL=CTL; the jobname of the TCAM MCP is TEST3; the following DD 
statement has been added to the EXEC statement for the TCAM MCP. 

//COMWRITE DD UNIT=SYSDA,DSN=COMWRITE, DISP=( ,KEEP ) , X 
// VOL=SER=456789,SPACE=(CYL,(5) ) 

(specifies that the COMWRITE data set be on disk); and the TCAM job is 
dequeued from the input stream and has just started execution. 

Example: 

1. Nothing has been entered at the IBM 1050 terminal. 

A. Entries are being made in the STCB trace table in main storage, and nothing 
is being written to the COMWRITE data set. 

B. Inactive. 

C. Inactive. 

2. CTLP TEST3,TRACE=052,ON ( eot ) 

A. Entries are still being made in the STCB trace table, and nothing is being 
written to the COMWRITE data set. 

B. Entries are now being made in the line I/O trace table in main storage for 
line 052, and nothing is being written to the COMWRITE data set. Re- 
sponse message 

IED023I TRACE STARTED FOR 052 

is sent to the IBM 1050 indicating that the line I/O trace was started for 
line 052 as requested by the GOTRACE command. 

C. Inactive 

3. CTL F TESTS , DEBUG=L , lEDQFE 1 ( eot ) 

A. Entries are still being made in the STCB trace table, and now the STCB 
trace table entries are being written to the COMWRITE data set. Response 
message 

IED099I ROUTINE LOADED 

is sent to the IBM 1050 indicating that the STCB trace table entries are 
being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for line 052, and 
nothing is being written to the COMWRITE data set. 

C. Inactive. 

4. CTLF TEST3,DEBUG=L,IEDQFE30 (eot) 

A. Entries are still being made in the STCB trace table, and STCB trace table 
entries are still being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for Une 052, and 
nothing is being written to the COMWRITE data set. 
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C. Since line I/O trace is active for line 052, buffer and status information for 
line 052 is now being written to the COMWRITE data set. Response 
message 

IED099I ROUTINE LOADED 

is sent to the IBM 1050 indicating that buffer and status information is 
being written to the COMWRITE data set. 

5. CTL F TEST3 , TRACE=03 1 , ON ( eot ) 

A. Entries are still being made in the STCB trace table, and STCB trace table 
entries are still being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for line 052, entries 
are also being made now in the line I/O trace table in main storage for line 
031, and nothing is being written to the COMWRITE data set. Response 
message 

IED023I TRACE STARTED FOR 031 

is sent to the IBM 1050 indicating that the line I/O trace was started as 
requested by the GOTRACE command. 

C. Since line I/O trace is active for lines 052 and 031, buffer and status 
information for these lines is being written to the COMWRITE data set. 

6. CTLF TEST3,DEBUG=L,IEDQFE20 (eot) 

A. Entries are still being made in the STCB trace table, and STCB trace table 
entries are still being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for lines 052 and 031, 
and now line I/O trace table entries are being written to the COMWRITE 
data set. Response message 

IED099I ROUTINE LOADED 

is sent to the IBM 1050 indicating that line I/O trace table entries are now 
being written to the COMWRITE data set. 

C. Since line I/O trace is still active for lines 052 and 031, buffer and status 
information for these lines is still being written to the COMWRITE data set. 

7. CTL F TEST3 , TRACE=052 , OFF ( eot ) 

A. Entries are still being made in the STCB trace table, and STCB trace table 
entries are still being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for line 031, but not 
line 052, and line I/O trace table entries for line 031 are being written to 
the COMWRITE data set. Response message 

IED029I TRACE STOPPED FOR 052 

is sent to the IBM 1050 indicating that the line I/O trace was stopped for 
line 052 as requested by the NOTRACE command. 

C. Since line I/O trace is now active only for line 031, buffer and status 
information for line 03 1 is still being written to the COMWRITE data set. 

8. CTLF TEST3,DEBUG=D,IEDQFE30 (eot) 

A. Entries are still being made in the STCB trace table, and STCB trace table 
entries are still being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for line 031, and line 
I/Otrace table entries for line 031 are still being written to the COM- 
WRITE data set. 



Using TCAM Service Facilities 525 



C. Inactive. 

9. CTL F TEST3 , DEBUG=D , IEDQFE20 ( eot ) 

A. Entries are still being made in the STCB trace table, and STCB trace table 

entries are still being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for line 031, but now 
nothing is being written to the COMWRITE data set. Response message 

IED100I ROUTINE DEACTIVATED 

is sent to the IBM 1050 indicating that no Une I/O trace table entries are 
being written to the COMWRITE data set. 

C. Inactive. 

10. CTL F TEST3 , DEBUG=D , lEDQFE 1 ( eot ) 

A. Entries are still being made in the STCB trace table, but now nothing is 
being written to the COMWRITE data set. Response message 

IED1 001 ROUTINE DEACTIVATED 

is sent to the IBM 1050 indicating that no STCB trace table entries are 
being written to the COMWRITE data set. 

B. Entries are still being made in the line I/O trace table for line 031, and 
nothing is being written to the COMWRITE data set. 

C. Inactive. 

11. CTL F TESTS, TRACE=031 , OFF ( eot ) 

A. Entries are still being made in the STCB trace table, and nothing is being 
written to the COMWRITE data set. 

B. Inactive. Response message 

IED029I TRACE STOPPED FOR 031 

is sent to the IBM 1050 indicating that entries are no longer being made in 
the line I/O trace table. 

C. Inactive. 

COMEDIT Printing Utility 

The COMEDIT utility is a separate job or job step that formats and prints in 
hexadecimal the specified output from the COMWRITE data set. The 
COMWRITE data set may contain any combination of entries from the STCB 
trace table, the I/O interrupt trace table, and buffer and status information. If the 
COMWRITE data set is on magnetic tape, a search option may be invoked to 
begin formatting the STCB trace dump at a specified time stamp (if the search 
option is requested and the COMWRITE data set is on disk, error message 

IED120I 'BLOCK=' PARM REQUIRES TAPE INPUT 

is returned to the system console and the printing utiUty formats and prints all the 
data from the physical beginning of the COMW^RITE data set). The number of 
Unes printed per page on the listing may be varied if the default value of 60 is not 
desired. Options that may be specified on the PARM= parameter of the EXEC 
statement are: 

Option Function Provided 

STCB Provides a formatted printout of the dispatcher subtask 

trace table entries that are on the data set. 
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lOTR Provides a formatted printout of the line I/O interrupt trace 

table entries that are on the data set. 

BUFF Provides a hexadecimal and EBCDIC formatted printout of 

buffers and any trace records, other than STCB and lOTR, 
that are on the data set. 

If neither STCB, lOTR, nor BUFF is specified, then all blocks are formatted and 
the hexadecimal dump contains all unknown records. 

BLOCK=hhmmddd This keyword value is valid only for a tape data set; it 

designates the starting point for formatting records from the 
data set. 

hh is replaced by a 2-digit decimal integer that specifies the 
hour in continental time. 

mm is replaced by a 2-digit decimal integer that specifies 
the minutes of the hour (using 1 -minute intervals). 

ddd is replaced by a 3 -digit decimal integer that specifies 
the day of the year (using JuUan days). 

LINECNT=xx Specifies the number of lines to be printed per page, where 

XX may be replaced by any 2-digit decimal integer up to 99. 
If this keyword parameter is omitted, a value of 60 is as- 
sumed. 

These options may be coded in any order and as often as desired. If keyword 
parameters are specified more than once, only the last dupUcate parameter is 
honored. If a parameter is coded incorrectly, the entire parameter Ust is printed on 
the SYSPRINT data set and the location of the parm scan pointer is shown, 
indicating the approximate location of the erroneous parameter. 

Examples appear below for invoking various combinations of entries from the 
COMWRITE data set; the ddnames SYSPRINT and SYSUTl are required names 
for the DD statements in this program. The DCB attributes for SYSPRINT are 
DSORG=PS,RECFM=FBA,LRECL=121,BLKSIZE=1331. 

Example 1 : 

Prints only STCB trace table entries from the disk COMWRITE data set, and 
specifies a Une count of 80 for the printed Usting. 

//jobname JOB 

//stepname EXEC PGM=IEDQXB, PARM=' LINECNT=80 , STCB' 

//SYSPRINT DD SYSOUT=A 

//SYSUTl DD DSN=COMWRITE,UNIT=SYSDA,VOL=SER-xxxxxx,DISP-OLD 

Example 2: 

Prints STCB trace table entries and Une I/O interrupt trace table entries from 
tape; specifies printed listing to begin at 10:15 pm on August 20, 1970, and 
specifies line count of 58. 

//jobname JOB 

//stepname EXEC PGM=IEDQXB, PARM= * IOTR,BLOCK=22 1 5232 , X 

// STCB , LINECNT=58 ' 

//SYSPRINT DD UNIT=OOE 

//SYSUTl DD UNIT=2400,VOL=SER=xxxxxx,DISP=OLD,LABEL=( ,NL) 
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If the search option is earUer than the first time stamp on the data set containing 
the STCB trace table entries, the entire data set is formatted and printed. If it is 
later than the last time stamp, no printing is done and error message 

IED121I REQUESTED TIME NOT FOUND 

is returned. In addition to the STCB trace being formatted by time and date, 
queue control blocks are formatted by individually named fields. I/O interrupt 
trace table entries on the COM WRITE data set appear as 32-byte records with 
unit check and unit exception fields flagged. 

Example 3: 

Prints buffers from tape — standard label in; standard label out (for printing on 
another machine ). 

//jobname JOB 

//stepname EXEC PGM^IEDQXB, PARM== ' BUFF ' 

//SYSPRINT DD DSN=dsname , UNIT=2400 , VOL==SER=xxxxxx , DISP=( ,KEEP ) 

//SYSUT1 DD UNIT-2400,VOL=SER=xxxxxx,DISP=OLD,DSN=COMWRITE 

Example 4: 

Prints buffer and status information and Hne I/O interrupt trace table entries from 
tape; specifies Hne count of 65 (if dupHcate keyword parameters are specified, the 
last value coded is used). 

//jobname JOB 

//stepname EXEC PGM=IEDQXB, PARM= ' LINECNT=1 ,BUFF, lOTR, X 

// LINECNT=65' 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD UNIT=2400,VOL=SER-TRACE,DISP=OLD,LABEL=( ,NL) 

If the PARM= parameter is omitted, all the entries on the COMWRITE data set 
are formatted and printed. If a coding error is detected in one of the keyword 
values of the PARM= parameter, error message 

IED123I INVALID PARAMETERS 

is returned indicating that the COMEDIT printing utility cannot be continued due 
to invaHd JCL; replace the invalid JCL card and resubmit the job. 

Message Queues Data Set Dump 

TCAM provides a separate utility (lEDQXC) that formats the DASD message 
queues data set for immediate printing, or it directs the messages queues data set 
to either magnetic tape or disk for later printing (see the discussion on 
Preformatting DASD Message Queues Data Sets in the chapter System 
Preparation ). The entire data set may be printed sequentially either by record 
number or by queue. Also, up to five individual queues may be printed. Individu- 
al reusable queues cannot be dumped after the message queues data set has been 
wrapped. The contents of the formatted dump are controlled by options in the 
PARM= parameter of the EXEC statement. The general format of the EXEC 
statement is: 

//STEP1 EXEC PGM=IEDQXC,PARM-'Q=opt ions' 

Options that may be specified on the PARM= parameter of the EXEC statement 
are: 

Option Function Provided 

DMP Prints all messages sequentially by 

record number. 
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xxx,DMP 



Prints all messages sequentially, where 
XXX is replaced by the 3 -digit decimal 
total number of queues. 



Specifying xxx , DM? gives the same results as either specifying DM? alone or 

omitting the PARM= parameter. 

To find total number of queues from the assembly hsting of the MCP, look 

for ORG lEDNADDR in the expansion of the macro that is named by 

TTABLE l.kST=name. Following that ORG is the line DC Mn *4 + 1), 

A(r *4 + 3). The value oin (for nonreusable disk) or r (for reusable disk) 

is the maximum value for Q=xxx in the PARM= parameter of the lEDQXC 

routine. 

xxx,ALL Prints all messages sequentially by 

queue, where xxx is replaced by the 3- 
digit decimal total number of queues. 



xxx,qiq^q^,q2q2q2, 

••^15^5^5 



Prints all messages for queues q^ q^ q^ 
through q^qsqg (up to 5 queues may be 
specified); xxx is replaced by the 3 -digit 
decimal total number of queues, and qqq 
is replaced by the 3 -digit decimal number 
corresponding to the queue (or queues) 
whose contents are to appear in the 
dump, qqq can be determined using the 
DC located at hexadecimal 28 from the 
first DC in the QCB CSECT in the 
TERMINAL or TPROCESS macro ex- 
pansion. The format of the DC is: 



DC 3AL ( yyy),5AL( ),AL1(ppp, 
AL3( 0) 

where yyy corresponds to the queue 
number and ppp is the priority level of 
that queue. There is one such DC for 
each priority level designated for the ter- 
minal. The number of queues to be 
printed can be calculated using one of 
the following equations: 

For nonreusable queues 

qqq=(yyy+3)^4 

For reusable queues 
qqq=(yyy-l-l)^4 

Below are some sample JCL statements for invoking the lEDQXC printing 
facility. 

Each extent of the DASD message queues data set must be defined with a 
DISKQnn DD card, where nn is replaced by decimal 01 for the first extent, by 
decimal 02 for the second, etc. For single extent cataloged data sets, DSN= and 
DISP= are the only required parameters. For multi-extent (multivolume) data 
sets, the catalog information cannot be used. Each DD statement must have also 
UNIT =xxxx, VOL =SER=xxxxxx information. These DD statements must define 



Using TCAM Service Facilities 529 



On-line Test Function 



the volume identification in the same order as the volume identifications listed on 
the lEDQDATA DD card on the lEDQXA utility JCL used when creating the 
data set. 

Example 1 : Dumping queues sequentially 

//jobname JOB 

//stepname EXEC PGM=IEDQXC 
//DISKQ01 DD DSN=dsname,DISP=OLD 
//SYSPRINT DD UNIT=OOF 

Example 2: 

Printing entire formatted queue 

//jobname JOB 

//stepname EXEC PGM=IEDQXC,PARM:=_Q=01 2 , ALL' 

//DISKQ01 DD DSN=dsname,DISP=OLD,UNIT-23xx,VOL=SER=1 11 1 1 1 

//DISKQ02 DD DSN=dsname, DISP=OLD, UNIT=23xx, VOL=SER=222222 

//DISKQ03 DD DSN=dsname, DISP^OLD, UNIT=23xx, VOL=SER=333333 

//SYSPRINT DD UNIT-OOE 

Example 3: 

Printing selected queues (there are eight queues on the data set; this JCL formats 
and prints queues 005,006, and 007 only) 

//jobname JOB 

//stepname EXEC PGM=IEDQXC, PARM- 'Q=008 , 005 , 006 , 007 ' 
//DISKQ01DD DSN=dsname,DISP=OLD,UNIT=23xx,VOL=SER=1 11111 
//DISKQ02DD DSN=dsname,DISP=OLD, UNIT=23xx, VOL-SER-222222 
//DISKQ03DD DSN-dsname , DISP=OLD , UNIT=23xx , VOL=SER=333333 
//SYSPRINTDD UNIT=OOE 

The PARM= fields are fixed format, and a coding error causes error message 

IED1 231 INVALID PARAMETERS 
to be returned to the system console; replace the invalid JCL and resubmit the 
job. 

The lEDQXC utility program suppresses printing of zero or non-data records 
during the sequential dump of a message queues data set. Consequently, the first 
record printed may not be the first physical record in the queue, and intervening 
zero records between data records in the queue are not printed. 



The on-line test (OLT) function is an optional TCAM facility; its implementation 
is described in detail in the 05 TCAM User's Guide , GC30-2025 . OLT permits 
either a system console operator or a remote control station user to test transmis- 
sion control units and remote stations. The OLT function is used to: 

Diagnose hardware errors 

Verify repairs 

Verify engineering changes 

Check devices periodically 

Check new stations brought on-line 

The TCAM OLT function is implemented in three parts: 
• the telecommunications on-line test executive (TOTE) 

TOTE acts as an interface between TCAM and the OLTs for scheduling and 
controlling the execution of OLTs. TOTE also prompts the user when he 
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Debugging Aid 
f 


Function 


Getting debugging 
aid to reside in 
main storage 


Dumping debugging 
aid to either tape or 
disk data set 


Printing debugging aid 
from tape or disk data 
set 


INTRO 
operands 


operator 
commands 


INTRO 
operands 


operator 
commands 




Standard 
OS Dump 




(Note 1) 
1 




TCAM Formatted 
ABEND Dump 




1 

(Note 2) 
1 




See the IFCEREPO system utility in the OS 
Utilities Publication for printing the contents 
of the SYSI. LOGREC data set. 


I/O Error 
Recording 




1 

(Note 3) 

1 




TCAM 
Logging 




1 

(Note 4) 




\ 


Cross- Reference 
Table 


CROSSRF=n 








STCB 
Trace 


DTRACE=n 




DTRACE=n 
COMWRTE=YES 


DEBUG (L, 
lEDQFElO) 


Use the COMEDIT printing utility 
described in this section. 


Line 
Trace 


TRACE=n 


GOTRACE 
NOTRACE 


TRACE=n 
COMWRTE=YES 


GOTRACE 
DEBUG (L, 
IEDQFE30) 


Buffer 
Trace 






TRACE=n 
COMWRTE=YES 


GOTRACE 
DEBUG (L, 
IEDOFE20 


/ 


Message Queues 
Data Set Dump 








IEDQFE30 


Use the lEDQXC utility program 
described in this section. 



Notes: 

1 . See the OS publication Programmer's Guide to Debugging . 

2. See the TCAM Program Logic Manual . 

3. See TCAM I/O Error-recording Facility in this chapter. 

4. See Using TCAM's Message Logging Facility elsewhere in this publication. 



Figure 38. Coding Requirements for Using TCAM Debugging Aids 



requests help, when he makes an invalid request, or when a test needs more 
data. 

a configurator 

The configurator contains such data as telephone numbers, what devices are 
attached to what channel addresses, features installed, and any other data the 
on-line tests need to tailor needs for testing all the equipment at a specific 
location. 

on-line tests (OLTs) 

The OLTs are device tests that run under the supervision of TOTE. They 
reside in a private library. The results are sent to a station specified by the test 
requester. On-line tests affect application performance to the extent that test 
transmissions require line time, tests require CPU time, and OLT modules 
require main storage and DASD space. 






Advantages of TOTE 



To properly assess the resources required to support TOTE, it is necessary to put 
TOTE in the proper perspective. TOTE is advantageous because it provides: 
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Dynamic remote test request 

Remote test control 

BSC support 

Operation in a dedicated TP system 

The on-line test concept allows device testing to be concurrent with other jobs 
within the computer. TOTE goes even further by allowing concurrent testing on a 
communication Une basis. TOTE will have one terminal on a multipoint commu- 
nication Une while the rest are still doing the customer's job. As an attached 
subtask of TCAM, TOTE can: 

1. Start an On-Line Test on a particular resource. 

2. Pause testing at a logical break point; 

3. Return the line, but not the particular resource, to TCAM to allow other 
programs to use the line; 

4. Regain control of the Une to continue testing; 

5. Continue this sharing of the line or end the test at the discretion of the OLT. 

In addition to the above advantages TOTE also allows any TCAM device capable 
of entering alphanumeric or numeric data to enter the Test Request Message 
(TRM), any TCAM device to be the test terminal, and any TCAM device capable 
of entering and printing data to be the control terminal, and any TCAM device 
capable of printing data to be the alternate printer. Thus up to four terminals may 
be used to start, control and report results of a given OLT or all these functions 
may be performed on the same terminal. 



Devices Supported 



OLTs for the following terminal devices will be supported by TOTE. Theoretical- 
ly, all TCAM stations may act as control terminals or alternate printers. However, 
since the input and output capabilities of different terminals vary, exercise caution 
in the selection of the control terminal and alternate printer to insure that 
the capability of the control or print device is compatible with its role. 



1030 


2780 


3277 


1050 


2848/2260 Local 


3284 


1060 


2848/2260 Remote 


3286 


27401 


2845/2265 




2740 II 


1130 (Terminal) 




2741 


2020 (Terminal) 




2760 


S360 (Terminal) 




2770 


3275 





Note: More terminal OL Ts are under development and will be supported 
when available. 



The following control units are supported by TOTE: 

7770 



2701 
2702 



2703 
3705 



3271 

3272 



System Requirements 



This section describes main-storage requirements, TCAM MCP facilities that must 
be specified to support on-line testing, OS/SYSGEN options that must be speci- 
fied, and JCL requirements for TOTE/OLTs. 
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Main-Storage Requirements 



In addition to the storage required for TCAM, the on-line test facility requires 
storage. This storage is reserved by the OLTEST parameter of the INTRO macro 
of TCAM's Message Control Program. 0LTEST=12 reserves 12K of storage for 
TOTE'S use. 



Coding Requirements 



The minimum amount of storage to allov^ on line testing is 12K bytes. Additional 
storage if reserved will allow larger OLTs or multiple asynchronous tests to be 
run. The amount of storage required is a function of the number of on-Une tests to 
be run concurrently but asynchronously. The first test requires 8K bytes plus the 
storage for the OLT. Each additional test requires 4K bytes for TOTE plus the 
storage for the OLT. 



During set-up and assembly of the TCAM MCP the following actions are required. 

1 . The OLTEST= operand of the INTRO macro in the MCP must be set to a 
value representing the additional TCAM storage needed to include the OLT 
function. 0LTEST=12 would specify 12K (8K for TOTE and 4K for the 
device test). Each increment of one would mean an additional IK. If the 
OLTEST= operand is not specified at TCAM assembly time, a default of 12 is 
assigned. To delete the OLT function from TCAM, set the OLTEST= operand 
to zero (OLTEST=0). The minimum value of OLTEST is 12. 

2. A new parameter of the TTABLE macro should be entered. This parameter 
specifies the number of dummy entries in the Terminal Table Entries available 
for TOTE's use as well as a work area. TOTE will use this area during execu- 
tion of an OLT. Imitation' Terminal Table Entries will be constructed in this 
area to allow TOTE to communicate through TCAM's message handling facilities. 
The operand is OLTERM=n. This operand will generate n dummy Terminal 
Name Table entries, as well as a work area containing 120 bytes for each 
dummy entry. These work areas are contiguous. Therefore, if n=6 an area 
containing 6 x 120=720 bytes is reserved for TOTE's use. If this operand is 
omitted, the default is OLTERM=0. If zero dummy entries are allocated to 
TOTE, then no remote station can be the control terminal or the alternate 
printer. 

3. Each terminal on a non-switched line used or tested by TOTE must have a 
symbolic name assigned to it in the TERMINAL macro. For switched lines a 
symbolic name should be assigned for each group of terminals having the same 
configuration. (For example, 2741s using correspondence code might be 
assigned a symbolic name of KGN2741 and 2741s using BCD code assigned a 
symbolic name of RAL2741 .) 

4. Each terminal used as control terminal or alternate printer by TOTE must 
have standard TCAM translation tables specified in its DCB. 

5. Sufficient storage for both TCAM and TOTE must be provided in the region 
parameter in JCL for MVT systems or partition assignment in MET systems. 

6. DIAGMSG (the diagnostic message output device), the OLT library, and the 
configuration library must be defined by job control language cards (JCL). 

7. Since TOTE uses TCAM's message handling facilities to communicate with the 
user, the MCP must contain the CODE macro unless the line code is EBCDIC. 

8. All wrap lines must have a DCB and must be opened by the MCP. This 
requirement allows TOTE to run those IBM 2702 and 2703 tests that use 

the WRAP line to test the transmission control unit. In addition, this line must 
be closed by the MCP during closedown. If the WRAP line is not used by the 
MCP and does not have a data set attached to it the UCB must be specified as 
a dial unit. This allows TCAM's Operator Control facilitiy to perform success- 
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fully the functions requested of it by TOTE. The Operator Control facility may 
have to be used to vary the WRAP line off-line if errors are reported by the 
message v 01d,offtp,i. 
9. Each on-Une test request must fit within a single buffer; furthermore, an on-line 
test message identifier (either SOH%/ or 99999) must fit within the first 
buffer unit. These buffer design considerations must be taken into account 
when the user specifies buffer sizes and buffer unit sizes (see the KEYLEN= 
operand of the INTRO macro instruction and the BUFSIZE= operand of the 
line group DCB macro instruction). 



TOTE Requirements 



Hardware Requirements 



The following requirements must be met before executing TOTE: 

1. The TCAM Operator Control facility must be initialized. 

2. The OLT modules must have been placed in a library. 

3. The Configuration Data Set (CDS) must have been built by stand-alone, on-line 
Test Support Program. 

4. The terminals must be represented in the TCAM JCL by a DD card. 

The following requirements must be met before executing a device test: 

1. The devices and communication hnes used or tested must have been config- 
ured. 

2. The devices used as control terminal or alternate printer must be on opened 
communication hnes. 

3. The communication lines to be tested must have been opened. 

4. The symbolically named devices to be tested must be on opened communica- 
tion lines. 

For TCU tests: 

The TCU lines to be tested must be available for testing allocated to TCAM and 
assigned to TOTE by the stop line command, since the lines used for testing are 
made unavailable to TCAM for the duration of the test. A terminal from which to 
control the test must be available also. The control terminal can be a TCAM 
terminal or display terminal not on the line(s) being tested, or the system console. 
The TCU test automatically forces the non-concurrent mode (NCM) request. 
Thus, the system operator must concur before TCU testing is allowed. 

For terminals: 



The tested terminal must be available for testing, since it is made unavailable to 
TCAM for the duration of the test. If the non-concurrent mode option is selected, 
the entire subchannel address will be unavailable for use by TCAM. A terminal 
from which to control the test must be available also. This terminal can be the 
tested terminal, another terminal (recommended to be near the test device), or the 
system console. Caution must be exercised when specifying the control terminal 
and the test device as the same device if hardware errors are occuring on the 
test device because: 

(1) It may be impossible to enter the information necessary to run the test. 

(2) TCAM may not recognize the message as a TRM. Instead of sending the 
TRM to TOTE, it may be sent to a Message Processing Program. 

(3) The test results may not reach the control terminal. 

Scheduling and Loading Unit Tests 

The OLT sections are stored within a partitioned data set and are called into 
storage for execution by the TOTE module lEDQWE. These sections are loaded 



i 



5 34 OS/MFT and OS/M VT TCAM Programmer's Guide 



into the region or partition assigned to TC AM/TOTE and then executed. In 
order to be executed the sum of storage required for all OLTs and TOTE must 
not exceed the amount of storage allocated for on line testing at INTRO time, 
0=n where n is an integer equal to or greater than 12 and represents the amount 
of kilo-bytes reserved for on line testing. Test selection is achieved by entering a 
Test Request Message (TRM). The TRM may be entered from a TCAM station 
or from an operator control terminal or the system console. The general format of 
a TRM is: 



Prefix Control Terminal/Test Devices/Tests/Options/ 



99999 
Prefix = SOH%/ 

modify Tcamjob,OLT= 

opid modify TCAMjob,OLT= 



: Start/ Stop or local 22xx 
:BSC or local 32xx 
ifrom system console 
.from operator console 



Control Terminal is the symboUc name of the station from which the test is to be 
controlled. The control terminal must be one of the stations supported by 
TCAM/TOTE. 

Test Devices are the list of symbolic names of terminal devices to be tested. If the 
test request is for a local control unit this field contains the physical addresses to 
be used. 

Tests identifies the on-line tests to be executed. One or more tests may be entered 
as well as selecting individual routines of a given test. 

Options specifies those options that will control the test procedure. Entries are 
delimited by commas. If the TRM contains no options default options are used. 

The above TRM is equivalent to: 

99999PHIL34/NYC01/1060AA/MI/ 



Prompting 



Information required for TOTE to run OLTS can be entered in the prompting 
mode. This mode can be entered upon the receipt of an invaUd entry in a TRM, or 
it can be requested. Upon entering the prompting mode the user is asked a series 
of questions designed to obtain the required information. If he entered prompting 
mode because of an error in his TRM, he is given the option of being prompted. 

Each time an invaUd entry is made in prompting mode, the user is given the option 
to discontinue prompting, or retry a TRM entry. If he chooses to continue he is 
given the chance to re-enter the information. 



Asynchronous Test Handling 



TOTE will run as many asynchronous OLTs as resources permit. Basically two 
resources are required. The first is storage and the second is available entries in 
TCAM's Terminal Name Table. 



When TOTE has used the last of the storage assigned by the OLTEST operand, 
TOTE will reject incoming TRMs until storage becomes available. 
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If there is enough storage remaining to start another asynchronous TRM, TOTE 
examines the TRM to determine the number of Terminal Name Table (TNT) 
entries required. One is required for: 

a) a control terminal, 

b) an alternate printer. 

Thus a maximum of two entries are required. If the entries are available TOTE 
verifies that there is enough storage available in the dummy TTE area. If storage 
is not available the TRM is rejected. If storage is available the dummy TTE 
entries are generated by TOTE in the dummy TTE area and the OLT is loaded. 

OS/SYSGEN Requirements 

In order to support TOTE, the SUPRVSOR macro instruction must specify 
OPTIONS =ONLNTEST at system-generation time. 

At least two buffers must be specified in the WTOBFRS parameter of the 
SCHEDULR macro instruction when on-line tests are included in the generated 
system. 
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JCL Requirements for TOTE/OLTs 

The following DD statements must be included in the TCAM JCL that defines 
data sets when the on-line test function is to be included in the TCAM system: 

//STEP1 EXEC PGM=MAINTEST,REGION=250K,TIME=1440 
//STEPLIB DD DSN=SYS 1 . LRDDVL2 , DISP=OLD 
// DD DSN=SYS 1 . LOADLIB , DISP=SHR 
// DD DSN=SYS1 .TOTDVLP,DISP=OLD 

// DD DSN=SYS1 .0LT2LIB,DISP=SHR 1 

// DD DSN=SYS1 .CDSLIB,DISP=OLD 2 

//SYSABEND DD SYSOUT=A, SPACE=( CYL, ( 20 , 20 ) ) 

//OLTLIB DD DSN=SYS1 .0LT2LIB,DISP=SHR 3 

//CDSLIB DD DSN=SYS1 .CDSLIB,DISP=SHR 4 

//DIAGMSG DD UNIT=OFF 5 

//INARU DD QNAME=GARUQ 

//OUTARU DD QNAME=PARUQ 

//IN2760 DD QNAME=GET2760 

//OUT2760 DD QNAME=PUT2760 

//APPIN DD QNAME=GETQ 

//APPOUT DD QNAME=PUTQ 

//DISKDD DD DSNAME=SYS1 .SAMP1 ,DISP=( OLD, PASS ) 

//RESDISK DD DSNAME=SYS1 .RESUABL, DISP=( OLD, PASS ) 

//DD2260R DD UNIT=01D 

//DD27402 DD UNIT=01E AAA,BBB 2740 MOD 2 

//TOTE071 DD UNIT=071 

//TOTE072 DD UNIT=072 

//WRAPDD DD UNIT=010WRAP LINE FOR 2702 6 

//RALDD DD UNIT=011 RAL - 1050 DIAL 

//ATLDD DD UNIT=012 ATL - 2740 WITH CHECKING - UNIT 2 

//DD1050 DD UNIT=015 MARY AND HUYCK - 1050'S MULTIDROPPED TOGETHER 

//DURDD DD UNIT=017 DUR - 2740 WITH CHECKING - UNIT 1 

//WASDD DD UNIT=01A WAS , CHAR 2740 'S DIAL UNIT 4S5 

//NYCDD DD UNIT=018 NYC - 2740 WITH STATION CONTROL - UNIT 3 

//DD2260L DD UNIT=150 



Notes: 

/. DSN=SYS1.0LT2LIB==Lfbrary containing OLTs and local CDS 

records; must be concatenated to STEPLIB. 

2. DSN^SYSl.CDSLIB^Library containing remote CDS records; must be 

concatenated to STEPLIB, 

3. DDNAME OLTLIB ^Library containing OLTs and local CDS records; 

must oe specified. 

4. DDNAME CDSLIB = Library containing remote CDS records; must be 

specified. 

5. DDNAME DIAGMSG =Must be specified if the APSYSOUT option is 

desired. 

6. DDNAME WRAPDD = The wrap line (lowest channel address) of all 2702s 

and 2703s must be specified in and opened by the MCP for 

The wrap-line OLTs to function properly. If the user does not 
have a data set attached to the wrap line, the line should be 
specified as a dial line. 
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System Preparation 

This chapter provides information needed in setting up a teleprocessing system to 
be run under TCAM. It indicates the machine and device requirements of a 
TCAM system, touches upon system generation requirements pecuUar to TCAM, 
and describes the lEDQXA utiUty program provided by TCAM for preformatting 
message queues data sets on disk. The System Generation publication provides 
information for generating an IBM System/360 Operating System, including 
machine configuration and data processing requirements. 

Machine and Device Requirements 

TCAM operates under the operating system MFT-II and MVT environments on 
any System/360 Model 40 or above (that is, a CPU having at least 128K of main 
storage). The only additions to the minimum requirements of the System/360 
Operating System are: 

• All telecommunications terminals, except the IBM 2260-2848 Local, must be 
attached to either an IBM 2701 Data Adapter Unit Model I, an IBM 2702 
Transmission Control Model I, an IBM 2703 Transmission Control Model I, or 
an IBM 7770 Model 3 Audio Response Unit; they cannot be attached directly 
to a channel. 

• All IBM 2701, 2702, 2703, or 7770 control units that operate under TCAM 
must be attached to the System/ 3 60 through the multiplexer channel. 

A switch on the CE panel on the 2702 can be used to place a give line in CE mode 
for equipment checking. Care must be taken to ensure that no lines are in CE 
mode when TCAM is used, since no ending status will be returned to a SIO 
command that is issued by the system. 

• No device may be operated in burst mode on the multiplexer channel concur- 
rently with the operation of TCAM, except when the TCAM operation involves 
only the 2260 Display Complex (Local). 

The following additional features may be required: 

• The system ATTACH macro instruction must be specified for an MFT system. 

• The Une correction feature on IBM 1050 Data Communication Sys^tem termi- 
nals is necessary, if automatic retry is desired when a transmission error occurs. 

Control Units and Terminal Types Supported 

TCAM supports any combination of the IBM 7770 Audio Response Unit and the 
IBM 2701, 2702, or 2703 transmission control units on the same multiplexer 
channel. Up to eight control units can be attached directly to the multiplexer 
channel. TCAM also supports the IBM 2848 Display Control attached directly 
either to the multiplexer or a selector channel. Figure 39 below illustrates the 
device configurations supported by TCAM. 



Multiprocessing System 



TCAM supports the multiprocessing (IBM Model 65 MP) system with the 
configuration-control feature; this system is formed from two Model 65s operat- 
ing as a single, large-scale system under one control program. Since the Model 65 
MP permits simultaneous execution of two tasks in the system, the TCAM MCP 
can execute simultaneously with a TCAM application program. 
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IBM 1030Dafa Collecfion System 
IBM 1050 Data Communication System 
IBM 1060 Data Communication System 
IBM 2740 Communicotion Terminal 
IBM 2740 Model 2 Communication Terminal 
IBM 2741 Communication Terminal 
IBM 2760 Optical Image Unit 
IBM 2260 Display Complex (Remote) 
IBM 2265 Display Complex (Remote) 
AT&T 83B3 Selective Calling Stations 
WU Plan 1 15A Outstations 
TWX Models 33 and 35 
World Trode Telegraph Terminals 

IBM 1130 Computing System 

IBM 2770 Data Communication System 

IBM 2780 Data Transmission Terminal 

IBM 2790 Data Communications System 

IBM 3270 Information Display System 

IBM 3670 Brokerage Communication System 

IBM 3735 Programmable Buffered Terminal 

IBM 3780 Data Communication Terminal 

IBM System 3 

IBM System/360 Model 20 

IBM System/360 Models 25 and above 

IBM 1030 Data Collection System 

IBM 1050 Dota Communicotion System 

IBM 1060 Data Communication System 

IBM 2740 Communication Terminal 

IBM 2740 Model 2 Communication Terminu 

IBM 2741 Communication Terminal 

IBM 2760 Optical Image Unit 
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TWX Models 33 and 35 

World Trade Telegraph Terminals 

IBM 1030 Data Collection System 

IBM 1050 Data Communication System 

IBM 1060 Data Communication System 

IBM 2740 Communication Terminal 

IBM 2740 Model 2 Communication Terminal 

IBM 2741 Communication Terminal 

IBM 2770 Data Communication System 

IBM 2780 Data Transmission Terminal 

IBM 2790 Data Communications System 

IBM 3270 Information Display System 

IBM 3670 Brokerage Communication System 

IBM 3735 Programmable Buffered Terminal 

IBM 3780 Data Communication Terminal 

IBM System 3 

IBM System/360 Model 20 

IBM System/360 Models 25 and above 

AT&T 83B3 Selective Calling Stations 

WU Plan n5A Outstations 

TWX Models 33 and 35 

World Trade Telegraph Terminals 

IBM System/370 Models 135 and above 

IBM 2260 Display Complex (Local) 



Figure 39. Device Configurations Supported by TCAM (Part 1 of 3) 

System Generation Considerations 

TCAM facilities can be incorporated into an operating system by performing an 
operating system generation. This procedure is explained in the OS publication 
System Generation . 



Using system generation macro instructions, the user specifies the line configura- 
tion and device requirements of the telecommunications system being supported, 
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Figure 39. Device Configurations Supported by TCAM (Part 2 of 3) 



and any optional features required. TCAM is specified as an option in the 
ACSMETH= operand of the DATAMGT macro instruction. 

The GENERATE macro instruction is modified for TCAM: 

GENERATE: 1) A DD card will be punched for the SYSl .CQ548 component 
library before group three macros are called so that the attention routine to handle 
2260/2848 interrupts can be link edited into the nucleus. 2) A DD card will be 
punched for the SYS1.CQ548 component library before the group five macros are 
called, so that modules can be selected from it by SGIEC5TP. 3) SGIEC3TP and 
SGIEC5TP will be called if QTAM, BTAM, or TCAM is specified. 

lODEVICE and lOCONTRL: TCAM will support the 7770 Model 3 and 
2845/2701. 
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Figure 39. Device Configurations Supported by TCAM (Part 3 of 3) 



If TCAM specifies a switched line at system generation time, the lODEVICE 
macro for that Une must indicate either the AUTOCALL or AUTOANSR feature. 
These features are automatically generated if BSC2 is specified. 



There are four types of system generation; three of these affect the DATAMGT 
macro and therefore TCAM. 

1. Complete Operating System Generation: ACSMETH=(TCAM) must be 
specified and the TELCMLIB macro specified. 

2. Nucleus Generation: ACSMETH=(TCAM) must be respecified so current 
SVCs are retained when the nucleus is re-link edited. If TCAM is not respeci- 
fied, it will not be in the system generated by the nucleus generation. The 
TELCMLIB macro need not be respecified, but must have been specified in the 
complete operating system generation. 

3. Processor/Library Generation: No effect on TCAM. 

4. I/O Device Generation: ACSMETH=(TCAM) must be respecified so current 
SVCs are retained. The TELCMLIB macro need not be respecified but must 
have been specified in the complete operating system generation. 
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MFT users must allow enough SYSQUE space at SYSGEN time for attached 
subtasks — 180 bytes per ATTACH. The four attached subtasks are Checkpoint, 
Operator Control, Comwrite, and On-Line Test. Checkpoint, Comwrite, and 
On-Line Test are optional. TCAM will ABEND if enough space is not allocated. 

Preformatting DASD Message Queues Data Sets 

Since TCAM expects the disk message queues (both reusable and nonreusable) to 
be totally pref ormatted, the lEDQXA routine should be used to perform this task 
before initially running any TCAM job (TCAM automatically formats the disk 
message queues for either a warm or a continuation restart). At SYSGEN time, 
the lEDQXA routine is moved from SYS1.CQ548 to SYSl.LINKLIB along with 
other TCAM non-resident modules. As a utility program, it is executed in a 
separate step from the step executing TCAM. Sample JCL is shown in Figure 40. 

//jobname JOB 

//stepname EXEC PGM^IEDQXA 

//lEDQDATA DD DSNAME=anyname ,DISP=( , CATLG ) , * 

// SPACE =(CYL,(n,n), ,CONTIG), * 

// UNIT-(xxxx,y), * 

// VOLUME=SER=( aaaaaa , bbbbbb ,...), * 

// DCB=KEYLEN=mm 

Figure 40. Sample JCL for lEDQXA Utility 

The variables in the figure are defined as follows: 

anyname 

User selects any name for the data set. 

n 

Since the number of cylinders must be the same for all extents, both primary and 

secondary allocations must be identical. Allocation must be by cylinders. 

xxxx 

Any one disk message queue must have all extents on one type of disk, either all 

on 2311, 2314, or 3330 type disks. 

y 

The total number of volume serial numbers listed in VOLUME parameter. Maxi- 
mum is 16. 

aaaaaa, bbbbbb,... 

There is one extent per volume. List each volume serial number of each volume to 
contain one extent of the data set. aaaaaa is the first extent, bbbbbb is the 
second, and so on. A maximum of 16 volumes may be identified. 

mm 

Each record formatted contains a key and a data field, mm is the size of each 
key portion of the record. Contrary to traditional usage of these fields, TCAM 
sets up a short data field for internal control information and places the actual 
buffer data in the key field. The data field size is an internally fixed constant (6 
bytes), and the size of the key field (that is, mm ) must be identical with the 
buffer unit size, as specified by the KEYLEN= operand of the INTRO macro. 
Although the buffer unit in main storage contains an internally generated 12-byte 
prefix, only the first six of these bytes are used to define the data field on disk. 
I (Guidelines for determining a suitable buffer unit size are contained in the chapter 

Defining Buffers). 
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There is no difference in the creation of reusable or nonreusable disk message 
queues. The data set created by this routine may be used by TCAM as either one. 

In addition to the desired message queues data set, this routine sends a statement 
to the programmer's console. This statement contains a cumulative record count. 
Any error messages or an indication of successful completion are also sent to the 
console. 



H 
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Appendix A: TCAM Macro Formats 



A format illustration accompanies each macro instruction in this publication. The 
illustrations indicate which operands must be coded exactly as shown, which are 
required, which are variable, etc. The conventions stated to describe the operands 
are as follows: 

1 . Keyword operands are described by a three-part structure that consists of the 
(uppercase) keyword operand, followed by an equal sign (both of which must 
be coded), followed by a lowercase variable or an uppercase fixed value to be 
specified by the user. 

Examples: 

KEYWORD=value, METHOD=NORMAL 

2. Positional operands are described by a lowercase name, which is merely a 
convenient reference to the operand and is never coded by the programmer, or 
by an uppercase operand that is used exactly as shown. The programmer 
replaces the lowercase operand by an allowable expression as defined in the 
macro description. 



Examples: 

qtype , destname , mask , MESSAGE. 

3. Uppercase letters and punctuation marks (except as described in these conven- 
tions) represent information that must be coded exactly as shown. 

4. Lowercase letters and terms represent information that must be suppUed by the 
programmer. Restrictions (such as the maximum value that may be specified) 
are stated in the description of the operand under the macro description. 

5. An ellipsis (a comma followed by three periods) indicates that a variable 
number of items may be included. 

6. ^ 
Options contained within braces represent alternatives, one of which is 
chosen by the user when he codes the operand in which the braces appear. 






8. 



Information contained within brackets represents an option that can be 
included or omitted, depending on the requirements of the program. If 
more than one alternative is included within a single set of brackets, either 
of the alternatives may be chosen, or the operand may be omitted (that is, 
none of the alternatives are chosen). Operands that are not enclosed 
within brackets are required. 



Underlined elements represent an assumed value in the event a parameter 
is omitted. 



Conventions Used 



In describing and illustrating the coding of macro instructions, the following 
conventions are used. 

Register notation: Unless otherwise specified, a register (2 through 11) may be 
used. The number of the register must be enclosed in parentheses. 
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Error returns: Error return codes are returned in the right-hand byte of register 
15. 

Commas in operand field: Sometimes two optional keyword operands are listed, 
such as [A][,B]. The comma is to be omitted if A is omitted. The comma must 
not be omitted for positional operands that are specified in another way. 

Blanks in operand field: No blanks are allowed within the operand field. 
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Appendix B: Message Error Record 



A five-byte message error record is assigned by TCAM to each message for the 
duration of its processing by the incoming or outgoing group of a Message Han- 
dler; this message error record may be checked by macros coded in the inmessage 
or outmessage subgroup of that group. Each of the 40 bits of the message error 
record (except reserved bits) indicates the presence (when 1) or the absence 
(when 0) of a specific error condition that has affected or may affect successful 
processing or transmission of the message. Some of the errors that may be 
recorded in the message error record are transmission and equipment errors (for 
example, lost data, busout check), some are due to mistakes in entering a message 
(wrong sequence number, invalid origin code), and some are due to a shortage of 
system resources (insufficient number of buffers, insufficient space in a main- 
storage-only message queues data set). 

The TCAM user may code one or several error-handling macros in his Message 
Handler; among these are CANCELMG, ERRORMSG, MSGGEN, REDIRECT, 
and HOLD. CANCELMG may be coded in the inmessage subgroup only, while 
the others may be coded in either the inmessage or the outmessage subgroup. 
These macros each have an optional five-byte error-mask operand, which may be 
used to test the message error record, so that the error-handling macro for which 
the mask is coded is executed only if the errors specified in the mask have occur- 
red. When error-handling macros are coded in an inmessage subgroup, they test 
the message error record after the message is received from a station or applica- 
tion program; in the outmessage subgroup they test the message error record after 
the message is sent to a station or application program. 

The last byte of the message error record consists of the sense byte for the I/O 
device (in this case, the transmission control unit being used). When the unit 
check bit is turned on in the CSW during an I/O operation, a sense command is 
issued by TCAM, and the appropriate bits in the sense byte are turned on. The 
CSW and the sense command are described in the Principles of Operation . A 
detailed discussion of the meaning of each bit in the sense byte may be found in 
the component description SRL for the transmission control unit being used. 

The meaning of each bit in the message error record is shown below. Bit is the 
left-most bit and Bit 39 the right-most bit in each error record. 

Bit Meaning 

Header error 

The scan pointer has reached the end of the last segment in the message, but 
the end of the inheader or outheader subgroup has not been reached. 

1 Invalid origin code 

The ORIGIN macro found that the origin field in the incoming header 
contained a code that: 

a. did not correspond to the name of a station that was connected to the 
computer over a nons witched line, or 

b. did not correspond to any station name in any group (applicable only to 
stations on switched lines). 
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Bit Meaning 

2 Reserved I 

3 Sequence number high or not a valid number 

The SEQUENCE macro found a message sequence number that is not a 
valid decimal integer or is higher than the expected number for the next 
message originating from the station. When this error is detected, the 
expected sequence number is not changed. If the message is not canceled by 
the user, the same sequence number may appear in more than one message. 

4 Sequence number low 

The SEQUENCE macro found a message sequence number lower than the 
expected number for the next message originating from the station. The user 
may inadvertently use the same message number in more than one message. 
This bit can be used to detect such an error, thus allowing the user to re-send 
the corrected message. 

5 Reserved 

6 Insufficient buffers 

The TCAM buffer assignment routine was unable to provide sufficient 
buffers for the incoming message. Infrequent occurrences of this condition 
may be corrected by requesting the originating station to re-send the mes- 
sage. Frequent occurrences of this condition suggest that TCAM be rede- 
fined with a larger number of buffers. 

7 Cutoff error (input only) 

The CUTOFF macro found a buffer filled with identical characters or a 
message whose length exceeded the maximum allowable length. 
RVI error (output only) 

On a multipoint, buffered terminal, if RVI is received in response to selec- 4 

tion for a block other than the first, this bit and the text error bit are set. \i| 

8 MSMIN passed 

The percentage of the number of units specified by the MSUNITS= operand 
of the INTRO macro that are currently enqueued in the main-storage mes- 
sage queues data set has fallen to or below the number specified by the 
MSMIN= operand of INTRO. 

9 MSMAX passed 

The percentage of the number of units specified by the MSUNITS= operand 
of the INTRO macro that are currently enqueued in the main-storage mes- 
sage queues data set has risen to or above the number specified by the 
MSMAX= operand of INTRO; used to indicate impending fullness of the 
data set. 

10 Reserved 

1 1 Reserved 

12 TOTE not in system 

A request for on-line test has been detected by a STARTMH macro, but 
TOTE is not included in the OLT= operand of the INTRO macro instruc- 
tion. 

13 BSC abort 

An abort sequence was received from a BSC station. 

14 Invalid destination code 

A destination specified in the FORWARD macro is invalid because it does 
not have a matching entry in the terminal table. 

15 SOH%E, SOH%C, or SOH%R message 

1 6 Incoming message lost 

An incoming message has been lost due to lack of space in a main-storage- m 

only message queues data set. 



548 OS/MFT and OS/MVT TCAM Programmer's Guide 



Bit Meaning 

1 7 Invalid station identification 

An identification sequence sent from a station is invalid. 

1 8 Station inoperative 

The destination station for this message is in intercept mode, and messages 
are not currently being sent to it. 

19 Reserved 

20 User error 

This bit may be set by the user to indicate a logical error condition of his 
choosing. The bit is set by means of a TERRSET macro issued in a Message 
Handler. 

21 Format error 

Message from BSC station is in wrong format for BSC (for instance, text 
does not start with the required STX character). 

22 Hardware attention 

For output operations, hardware attention (causes bit 25 to be set). 

Threshold reached 

For input operations, the threshold has been reached on a main-storage-only 

queue. 

23 Unit exception 

The unit exception bit is on in the CSW, indicating the presence of a condi- 
tion that does not usually occur during an I/O operation. 

24 Error during invitation or selection 

An error occurred during invitation or selection (before text transfer). 

25 Error during text transfer 

An error occurred during transfer of data. This bit is also set if an abnormal- 
ly terminating appUcation program has sent a partial message to the MCP 
) with a PUT or WRITE macro, since TCAM automatically sends this partial 

message to the requested destination. 

26 Error during connection or disconnection 

An error occurred before invitation or selection, or while attempting to 
disconnect. 

27 Terminal error bit 

A terminal malfunction has occurred. 

28 Reserved 

29 Error in control unit 

A busout, equipment check, overrun, or similar error, recognized by the 
control unit as an error in the control unit, has occurred. 

30 Error in channel 

A channel control check, interface control check, channel data check, or 
command reject has occurred. 

31 Undefined error 

An error has occurred that cannot be classified by TCAM. 

SENSE BYTE 

32 Command reject 

A command or a series of commands is received that the device is not 
designed to execute or cannot execute because of its present state. 

33 Intervention required 

Some sort of intervention is required, or the device is in the not-ready state, 
or in test mode, or not on the control unit. 

34 Busout check 

I An invaUd parity character is received by the device or control unit. 

1^ 35 Equipment check 

The device has malfunctioned. 
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Bit Meaning 

36 Data check 

An error has occurred associated with the recording medium. 

37 Overrun 

The channel failed to respond on time to a request for service from a device, 
or a device received a new command too late during command chaining. 

38 Lost data 

39 Time-out exceeded 

More than the maximum allowable time elapsed between poUing or address- 
ing a station and reception of a response from it. 
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Appendix C: How To Make Transient Checkpoint and 

Operator Control Modules Resident 



Certain TCAM modules connnected with the TCAM checkpoint and operator 
control facilities are normally transient, but may be made resident if the user so 
desires. By making frequently used modules resident, the user increases the 
performance of his system, at the expense of additional main-storage space. 

The TCAM checkpoint and operator control modules that may be made resident 
are located in SYSl.LINKLIB. To make these modules resident, the user must 
first specify at system-generation time the Reenterable Load Module Made 
Resident option. This is done by specifying the OPTIONS =COMM and 
RESIDNT=RENTCODE operands of the SUPRVSOR system-generation macro; 
details are given in the System Generation publication. 

Before initial program loading (IPL), the user makes a Ust of the load modules he 
wishes to make resident and places it in SYSl.PARMLIB by means of the 
lEBUPDTE utility program. For more information on placing such a Ust in 
SYSl.PARMLIB, see the OS 5>^r^m Programmer's Guide. 

At IPL time, in response to the console message SPECIFY SYSTEM PARAMETERS , 
the operator provides the unique identification for the Ust, and the routines 
pointed to by the Ust are loaded into main storage. More information on replying 
to this message is contained in the Messages and Codes publication. 

The following checklists show: 

L In order of decreasing frequency of use, the ordinarily transient modules 

associated with TCAM checkpoint routines that may be made resident as 

described above. 
2. Ordinarily transient modules associated with operator commands that may be 

made resident. Some operator commands have more than one such module 

associated with them. 

Example: 

An MVT user wishes to make some operator control modules resident. At system 
generation time the user must code RESIDNT=RENTCODE and 
OPTIONS=COMM on the SUPRVSOR macro. 

The user might create a list named lEAIGGOC and a Ust named lEARSVOC to 
contain the operator control modules. The user would get the modules and their 
sizes from the checklist of modules. Sometime before IPL the lEBUPDTE utility 
program, as shown in the Figure 41, would be used to place the Usts in the 
SYSl.PARMLIB. 
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//RESIDENT JOB MSGLEVEL=( 1,1) 

//PERF EXEC PGM=IEBUPDTE 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSN=SYS1 .PARMLIB,DISP==SHR 

//SYSUT2 DD DSN=SYS1 .PARMLIB,DISP=SHR 

//SYSIN DD * 

./ ADD NAME=IEARSVOC,LIST=ALL 

SYS1 .SVCLIB IGC0010D,IGC01 1 OD, IGC07 1 OD, IGC01 OD, IGCVO 1 OD, 
IGCM010D 
./ ADD NAME=IEAIGGOC,LIST=ALL 

SYS 1 . LINKLIB lEDQNQ , lEDQNJ , lEDQNO 
/* 

Figure 41. Sample of using the lEBUPDTE Utilfty (before IPL) for placing 
list in SYSl.PARMLIB 

Note that the statements starting with SYSl. SVCLIB and SYSl. LINKLIB begin 
in column 2. 

At IPL time, in response to the console message 

EA101A SPECIFY SYSTEM PARAMETERS 
the operator might reply 

REPLY id, 'RAM=00,OC,RSVC=00,OC' 

where 00 are the last two characters in the name of the standard 

list of names of reenterable load modules, and OC are the last two characters 

in the name of the lEAIGGOC Ust. 



Checkpoint Modules and Their Sizes 

Module 



lEDQNG 

lEDQNH 

lEDQNJ 

lEDQNK 

lEDQNM 

lEDQNO 

lEDQNP 

lEDQNQ 



lEDQNR 
lEDQNS 



Description Decimal Size 

(Approximate) 

Incident Record for CHECKPT 250 bytes 

Incident Record for TCHNG 240 bytes 

Checkpoint/Operator Control 240 bytes 

Environment Checkpoint 800 bytes 

CKREQ 390 bytes 

Checkpoint Queue Manager 240 bytes 

Checkpoint I/O 640 bytes 
Checkpoint Notification/ 

Disposition 730 bytes 

No Main Storage 260 bytes 

Incident Overflow 160 bytes 



All of the following modules have a length of 1024 bytes. 

Module Description Most Used 



IGCDOIOD 
IGCDllOD 
IGCD210D 
IGCD310D 
IGCD410D 



Display Scan 

DPRIOPCL/DSECOPCL 

QSTATUS 

ACTIVATED/INACTVTD 

INTRCEPT 



i 
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Description 



Module 

IGCD5 1 OD STSTATUS 

IGCD610D RLNSTATN 

IGCD710D STATDISP 

IGCD810D OPTFIELD 

IGCD910D LNSTATUS 

IGCHOIOD SUSPXMIT 

IGCIOIOD ICHNG DEACTIVATE 

IGCIllOD ICHNG MOVE/ ACTIVATE 

IGCMAIOD MODIFY SCAN II 

IGCMO 1 OD MODIFY SCAN I 

IGCMl lOD MODIFY MSG MODULE 

IGCM210D AUTOSTOP/AUTOSTRT 

IGCM4 1 OD INTER VAL/SYSINTVL/POLLDLAY 

IGCM5 1 OD ERRECORD 

IGCM610D GOTRACE/NOTRACE 

IGCM7 1 OD CPRIOPCL 

IGCM810D DATOPFLD 

IGCM910D DEBUG 

IGCROIOD RESMXMIT 

IGCVOIOD VARY SCAN 

IGCVllOD STOPLINE 

IGCV210D NOENTRNG/NOTRAFIC 

IGC V3 1 OD STARTLINE 

IGCV410D ENTERING/ ACTVBOTH 

IGCZOIOD HALT SCAN 

IGCZIIOD SYSCLOSE 

IGCOOIOD CONSOLE/MPP/TOTE INTERFACE 

IGCO 11 OD TERMINAL INTERFACE 

IGC03 1 OD ERROR MSG MOD I 

IGC04 1 OD ERROR MSG MOD II 

IGC05 1 OD ERROR MSG MOD III 

IGC06 1 OD INCIDENT CKPT INTERFACE 

IGC07 1 OD OUTPUT WRITER 

IGC08 1 OD ERROR MSG MOD IV 

IGC09 1 OD VARY MSG MOD 



Most Used 



* 

* 
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Appendix D: Internal and Transmission Code Charts 



Two sets of charts are included in this appendix. Figure 42 comprises four foldout 
charts that include character sets and hexadecimal code for the extended binary 
coded decimal interchange code (EBCDIC), line codes for BSC devices 
(USASCII and 6-bit Transcode hexadecimal representations that correspond to 
EBCDIC), and line codes for start-stop devices (hexadecimal representations that 
correspond to EBCDIC). Figures 43 through 57 compose the second set of code 
charts; these figures illustrate, in collating sequence (from hexadecimal 00 to 
hexadecimal FF), the valid hexadecimal representations of graphic and control 
characters for each device. 

The first set of charts (Figure 42) is based on the collating sequence of the 
EBCDIC code that is used internally by the Operating System/ 3 60 Central 
Processing Unit (see column 3). Line code for BSC devices may be in either 
EBCDIC, USASCII, or 6-bit Transcode (columns 1 through 9). Columns 10 
through 48 represent the character and code sets for start-stop devices that 
correspond to the internal EBCDIC code hsted in column 3. 



Arrangement of Charts 



There are three columns associated with each entry in Figure 42. For instance, 
columns 1, 2, and 3 are associated with the EBCDIC entry, and columns 10, 11, 
and 12 are associated with the IBM 1030 entry. The "reference" columns on the 
left and right ends of Figure 42 contain numbers to designate rows. These num- 
bers can be used in conjunction with the column numbers to designate a particular 
entry on the chart; for instance, location 21/17, the intersection of row 21 and 
column 17, contains the control character CR (carriage return) for the IBM 1060 
Data Communication System. For ease of reference, column 49 repeats the 
EBCDIC code that appears in column 3. 

The arrangement of the charts in Figures 43 through 57 is based on the collating 
sequence of the hexadecimal representations of the Une code for the various 
devices. 

Thus, columns 1 through 3 in Figure 42 (in conjunction with the columns that 
correspond to the device that originally entered the message) may be used for 
decoding messages in a dump when those messages have already been translated 
by the appropriate translation table; if a message was entered by a BSC device 
whose Une code is EBCDIC, then columns 1 through 3 may be used for line code 
translation and internal System/360 translation. Figures 43 through 57 may be 
used to decode messages in a dump when the message appears in line code 
(incoming messages are in line code when they have not yet been translated to 
EBCDIC, and outgoing messages are in Une code when they have been translated 
from EBCDIC). 

Conventions Used in Code Charts 

In the code columns for the various devices in Figure 42, some hexadecimal 
representations appear in parentheses, some in brackets, and others in neither. 
Where parentheses are used, only outgoing translation is performed by the transla- 
tion table that corresponds to the device type for that column. For example, the 
alphabetical letter W in internal OS/360 code (EBCDIC) is represented by the bit 
pattern that corrsponds to a hexadecimal E6 (see locations 230/1 and 230/3). If 
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hexadecimal E6 is to be transmitted to an IBM 1060 Data Communication 
System, it must first be translated to the appropriate Hne code. The character is 
directed to the appropriate translation table where it is converted to hexadecimal ( 

2C (see locations 230/16 and 230/18), which is the hexadecimal representation 
of the appropriate line code for the character W to be transmitted to an IBM 
1060. Where the hexadecimal representation is enclosed in brackets (for instance, 
location 54/30), only incoming translation is performed; thus, hexadecimal 9C is 
translated to EBCDIC 36 when the uppercase key is pressed on an IBM 2741 
Communication Terminal using BCD code, (see locations 54/3, 54/29, and 
54/30). If there are neither parentheses nor brackets, both incoming and outgoing 
translation is provided for that device. 

Various code set options are indicated in the graphic columns in Figures 42 
through 57. Where S, H, A, and C appear as subscripts to a character, S indicates 
that the TCAM-provided translation table supports use of the standard code set 
for that device; H, A, and C indicate TCAM support of optional code sets for that 
device. For instance, at location 2/12, hexadecimal 16 is the outgoing line code to 
an IBM 1030 Data Collection System; the graphic characters at location 2/10 
indicate that a pound sign (#) is printed by the IBM 1033 Printer if the printer 
uses the standard character set, and an equal sign (=) if it uses the H option. See 
the component description SRL of the device for a description of the character 
sets that may be used (TCAM supplies translation tables for AT & T TWX 
terminals that use the standard option, and for AT & T 83B3 and Western Union 
1 15A terminals that use either A or C options). 

Because each unique bit pattern for a terminal character can be represented only 
once in an incoming translation table, the character associated with the bit pattern 
can be translated to only one EBCDIC character. The converse is not true, ? 

however; any one transmission code bit pattern can be placed any number of si 

times within an outgoing table. Therefore, any number of EBCDIC characters 
can be translated to the terminal character represented by that bit pattern. 

Appearance of two bit patterns opposite a single character signifies that the 
character has both an uppercase (or figures shift) and a lowercase (or letters shift) 
bit pattern, and that both forms pf the character are translated to the same 
EBCDIC character. (Exception: In the code column for TWX terminals, where 
two bit patterns appear, the left-hand one is the even-parity pattern, and the 
right-hand one is the non-parity pattern.) 

Example: 

The bit pattern of the NL character appears in location 21/15. Both the lower- 
case and uppercase bit patterns of this character are translated to the EBCDIC 
NL character when they appear in an incoming message. When an EBCDIC NL 
character appears in an outgoing message, TCAM translates it to the lowercase 
form of the NL character. 

Where more than one EBCDIC character requires translation to the same charac- 
ter in a terminal character set, the terminal character appears an equivalent 
number of times in the column (for instance, locations 0/38, 6/38, 7/38, 23/38, 
and 80/38 all contain the LTRS character). 

Where a character appears in both the graphics and the controls columns for a 
terminal type, its function depends on whether it is sent when the Hne is in control . 
mode or text mode. Depending on the type of terminal and the mode, the charac- a 



556 OS/MFT and OS/MVT TCAM Programmer's Guide 



ter may perform a control function, print as a graphic, or both. For details, see 
the reference manuals for the various terminal types. 

Nonequivalent Characters 

Designing the system to accomodate terminal types having different character sets 
and control functions has resulted in several instances where dissimilar characters 
have been equated in translation tables. This accounts for the appearance in 
certain rows in Figure 42 of non-equivalent characters, for example, in rows 3, 38, 
and 50. 

In other instances, the same or similar functions have different names among the 
various terminal types; for example, HT and Tab in row 5 are equivalent, as are 
DEL and Rubout in row 7. In a few instances, terminals using the same transmis- 
sion code have different meanings assigned to the identical bit pattern; for exam- 
ple, bit pattern 79 in the transmission code has the meaning PF for an IBM 1050 
(see 4/14), and the meaning Subtract for an IBM 1060 (see 4/17). 



Substitutions 



Where blank positions appear in the character columns of the charts, there is no 
equivalent internal EBCDIC character. Where these blanks appear, the SUB 
character is to be assumed (they were omitted to make the charts more readable). 
That is, in each translation table that handles incoming messages, each position 
representing an invalid transmission code bit pattern (that is, one not specified in 
the terminal's character set) is translated to the EBCDIC code 3F for the SUB 
character. In each translation table that handles outgoing messages, the transmis- 
sion code bit pattern for a substitute graphic is contained in each of the following 
positions: 

• Each position that represents an invalid EBCDIC bit pattern (a pattern to 
which no EBCDIC characters have been assigned). 

• Each position that represents a bit pattern for a character having no equivalent 
in the destination terminal's character set. 

For the IBM 1050, 2260, 2740, and 2741, this substitute character is a colon (:). 
For the IBM 1030 and 1060, and the AT & T TWX and 83B3, and the Western 
Union 1 15A, it is a slash (/). 



General Notes 



Standard abbreviations are used to represent the control characters. The full 
names of the characters are given in the section Control Characters below. For 
descriptions of these characters, see the reference manuals for the various termi- 
nals. 

Where a circle character ((§),(B), etc.) appears in parentheses adjacent to a 
control character, it is an alternate name for the control character. 

Most of the characters in the S and H character set options (1030) and in the A 
and C character set options (83B3, 1 15 A) are identical. Where they differ 
between the options, the translation tables favor the S option and the A option, as 
illustrated in the charts. If messages from an H option 1030 are sent only to 
another H option 1030, the translation table may be used as is, and similarly, for 
the 83B3/1 15A, with respect to the C option. If messages from terminals with 
the H or C option are to be exchanged with other terminal types, the user should 
provide his own translation tables. 
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Control Characters 



ACK 

® 

BEL 

BS 

BYP 

© 

CAN 

cc 

CR 
CUl) 

CU2> 

cus) 

® 

DCl) 

DC2> 

DC4) 

DEL 

DLE 

DS 

EM 

ENQ 

EOA 

EOB 

EOC 

EOFC 

EOM 

EOT 

ETB 

ETX 

FF 

FIGS 

FS 

HT 

IFS 

IGS 

IL 

IRS 

lUS 

LC 

LF 

LF-CR 

LTRS 

MZ 

NAK 

NL 

NUL 

PF 

PN 

PRE 

PZ 

RES 



Positive Acknowledgment 

End of block (same as EOB) 

Bell 

Backspace 

Bypass 

End of transmission (same as EOT) 

Cancel 

Cursor control 

Carriage (carrier) return 

Reserved for customer use 

Machine end-of-address (same as EOA) 

Device link escape 

Delete 

Data link escape 

Digit select 

End of medium 

Enquiry 

End of address 

End of block 

End of card 

End of first card 

End of message 

End of transmission 

End transmission block 

End of text 

Forms feed 

Figures shift 

Field separator 

Horizontal tabulate 

Interchange file separator 

Interchange group separator 

Idle 

Interchange record separator 

Interchange unit separator 

Lowercase shift 

Line feed 

Line feed-carriage return 

Letters shift 

Minus zero 

Negative response to polling, addressing, or LRC/VRC 

Negative acknowledgment 

New line 

Null 

Punch off 

Punch on 

Prefix 

Plus zero 

Restore 



i 
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RM 


Record mark 


RS 


Reader stop 


(D 


Start of address 


SI 


Shift in 


SM 


Set mode 


SMI 


Start manual input 


SO 


Shift out 


SOH 


Start of header 


SMM 


Start manual message 


SOS 


Start of significance 


SP 


Space 


STX 


Start of text 


SUB 


Substitute 


SYN 


Synchronous idle 


Tab 


Tabulate (horizontal) 


TM 


Tape mark 


TpAuxOff 


Tape auxiliary off 


TpAuxOn 


Tape auxiUary on 


UC 


Uppercase shift 


VT 


Vertical tabulate 


WRU 


'^Who Are You?" 


X-Off 


Transmitter off 


X-On 


Transmitter on 


® 


Positive response to polling, addressing, or LRC/VRC 



Appendix D: Internal and Transmission Code Charts 559 



i 



Insert foldout pages 561, 563, 565, and 567 located at end of this book 






i 



Ref. 


Inte 


rnal S/360 


































IBM 2260 (Remote)/2265 








2741 1 


AT&T 83 B3 


1 






L 


WT Telegraph 1 


EBCDIC 


Ref. 


Code (EBCDIC) 


USASCII 


6-Bit Transcode 


IBM 1030 


IBM 1050 


IBM 1060 


2260/2265 


1053 


IBM 2740 


BCD 1 


EBCD 1 


Correspondence 1 






ITA2 1 


__-f^hi , \ 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 

(Hex) 


Character 


Code 
(Hex) 


Character 


Co«te 
(H<fx) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) . 


Character | 


OxJe 


Character 1 


Code 
(Hex) 


Character | 


Code 

(Hek)^ 


Character 1 


Code (Hex) 
Even Non 


Character 


Code . 


Character 


Code 
(Hex) 


Code 
(Hex) 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


(Hex) 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


(Hex) 


Graphic 


Control 


1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


' 17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


31 


32 


33 


34 


35 


36 


37 


38 


39 


40 


41 


42 


43 


44 


45 


46 


47 


48 


49 



I 

2 
3 




NUL 
SOH 
STX 
ETX 


00 
01 

02 
03 




NUL 
SOH 
STX 
ETX 


00 
01 
02 
03 




SOH 
STX 
ETX 


(3F) 
00 
OA 
2E 


's =H 


Pad 

EOA(®) 
EOB(0) 


(DF) 
(37) 
(l<i) 
(3D) 


» 


IL 

EOA(®) 
EOB(®) 


(5E) 

(16) 
(3D) 


# 


IL 

EOA(®) 
EOB(®) 


(5E) 

(16) 
(3D) 




STX 
ETX 


02 
03 




STX 
ETX 


(02) 
(03) 


/ 


IL 

EOA^) 
EOB(®) 


(5E) 
(37) 
(16) 
(3D) 


/ 


EOA((D)) 
EOB(®) 


5E 

37 

16 

C3D3 
















LTRS 
CR 


(IF) 
(02) 




Rubout 
CR 


(FF) (FF) 
(81) (B1) 




LTRS 
CR 


(IF) 
(02) 




LTRS 
CR 


(IF) 
(02) 


00 
01 
02 
03 



1 

2 
3 


4 
5 
6 
7 




PF 
HT 
LC 
DEL 


04 
05 
06 
07 




HT 
DEL 


09 
7F 




HT 

DEL 


2F 

3F 




HT 
Pad 
EOC DEL 


(M) 
(DF) 
7F 




PF 
Tab 

Dwnshft 
DEL 


79 EF93 
7A I-FA3 
7C CFC3 
7F CFFD 




Subtr 
Tab 
IL 
DEL 


m 

7¥ 
















HT 

Dwnshft 

DEL 


7ACfa3 

7CCFC3 
7F CFF3 




HT 

Dwnshft 
DEL 


7A cfa: 

7C tFC~ 
C7F3CPF: 




HT 
LC 
DEL 


c'iBi 




Tab 
Dwnshft 


7A tFA3 
7C tFC3 




LTRS 
LTRS 


IF C3F3 
OF) . 




TpAuxOff 
HT 

Rubout 


28 29, 
90 91 

FF FF 




LTRS 
LTRS 


IF C3F3 
(IF) 




LTRS 
LTRS 


IF C3F3 
OF) 


04 
05 
06 
07 


4 
5 
6 
7 


8 
9 
10 
11 




SMM 
VT 


08 
09 
OA 

00 




VT 


OB 


























► 


SMI 


RD 




<? 




































VT 


0\ D1 














08 
09 
OA 
OB 


8 
9 
10 
11 


12 
13 
14 
15 




FF 
CR 
SO 
SI 


oc 

OD 

OE 

OF 




FF 
CR 
SO 
SI 


OC 
OO 
OE 
OF 










LF-CR 


(5B) 




NL 
BYP 
RES 


(58) 
(38) 
(58) 




CR 


(5B) 


Ji 


NL 


.(OA) . 




NL 


(OA) 




NL 


(58) 




LF-CR 


m 




NL 


(5B) • 




LF-CR 


(5B) 




CR 


(02) (22) 




FF 
CR 
SO 
SI 


30 31 
(81) (Bl) 
71 71 
FO Fl 




CR 


(02) 




CR 


(02) 


OC 
OD 
OE 
OF 


12 
13 
14 
15 


16 
17 
18 
19 




DLE 
DC I 
DC2 
TM 


10 
11 

la 

13 




DLE 
DCl 
DC2 
DCS 


10 
11 
12 
13 




DLE 


IF 
































































X-On 


88 89 














10 
11 
12 
13 


16 
1Z 
18 
19 


20 
21 
22 
23 




RES 
NL 
BS 
IL 


i? 




LF 
BS 
NUL 


(OA) 

08 

(00) 




DEL 


(3F) 




LF-CR 
Pad 


,<58) 
(DF) 




RES 
NL 
BS 
IL 


58 tD83 
58 C0B3 
5D CDCQ 

SB toa 


• 


CR 
IL 


(58) 
(5B) 

(5E) 


A 


NL 


OA 




NL 


(OA)' ^ 




NL 
BS 
IL 


5B C D83 
5DCDDD 
5E C ^^1 




RES 
LF-CR 
BS 
IL 


58 COSl 

5B cdb:] 

5D CDD3 
5E CDE3 




RES 
NL 
BS 


58 tDJd 
5B CD83 




RES 
LF-CR 
BS 
IL 


58 Cob3 
50 CDca 

5E 




LF 
LTRS 


08 C283 
(IF) 




LF 
Rubout 


50 [513 

m) (rF) 




CR 
LTRS 


02 1:223 
OF) 




CR 
LTRS 


02 C223 
OF) 


14 
15 
16 
17 


20 
21 
22 
23 


24 
25 
26 
27 




CAN 
EM 
CC 
CUl 


18 
19 

lA 
IB 




CAN 
EM 


18 
19 




EM 


3E 




















a 


CAN 
Check 


083 

42 


" 




(42) 










PRE 


3E 






































18 
19 
lA 
IB 


24 
25 
26 
27 


28 
29 
30 
31 




IFS 
IGS 
IRS 
lUS 


IC 
ID 
IE 
IF 




FS 
GS 
RS 
US 


\C 
ID 
IE 
IF 




US 


ID 
















































































IC 
ID 
IE 
IF 


28 
29 
30 
31 


32 
33 
34 
35 




DS 

SOS 

FS 


20 
21 
22 
23 




























































































20 
21 
22 
23 


32 
33 

34 
35 


36 
37 
38 
39 




BYP 
LF 

ETB(EOB) 
ESC(PRE) 


24 
25 
2d 
27 




LF 
ETB 
ESC 


OA 
U 
18 




ETB 
ESC 


OF 
2A 




LF 
EOB(®) 


(38) 

- m 




BYP 
LF 

EOB 
PRE 


38 CB83 

38 CftftJ 
3D CBD3 

3E tUl 




LF 
EOB(®) 


(38) 
3D 




ETX 


(03) 




ETX 


(03) 




Index Attn 

EOB 

PRE 


38 11883 
3D C 803 

3E . 




BYP 

Index Attn 
EOB(®) 


38 

38 CB83 

DDlCBD^ 




BY 
LF 
EOB 
PRE 


38 XbCI 
38 t&H 




BYP 

Index Attn 
EOB(®) 
PRE 


38 

38 C883 

3E 




LF 
CR 


(08) 
02 C223 




LF 
CR 


(50) (51) 
81 CBI3 




LF 
WRU 


08 C283 

(08) m 




LF 
WRU 


08 C2C1 
(08) \ D23 


24 
25 
26 
27 


36 
37 
38 
39 


40 
41 
42 
43 




SM 
CU2 


28 
29 

2A • 
2B 










































'':^ i;: 








































Bell 


3A 




Bell 


2C 


28 
29 
2A 
2B 


40 
41 
42 
43 


44 
45 
46 
47 




ENQ 
ACK 
BEL 


2C 
2D 
26 
2F 




ENQ 
ACK 
BEL 


05 
06 

07 




ENQ 
BEL 


2D 
OD 






















ACK 


06^" 




1 

ACK 


0^>.; 


























'c 


Bell A 


3A 




WRU 
Bell 


AO EAI3 
£1 El 














2C 
2D 
2E 
2F 


44 
45 
46 
47 


48 
49 
50 
51 




SYN 


30 
31 
32 
33 




SYN 


\$ 




SYN 


3A 




Pad 


\0F) 




IL 


i5n 




IL 


(5E> 
















IL 


{5E) 




IL 


.(51) 




IL 


m 










LTRS 


m 




Rubout 


(FF)(Ff) 




LTRS 


(IF) 




LTRS 


K\^ 


30 
31 
32 
33 


48 
49 
50 
51 


52 
53 
54 
55 




PN 
RS 
UC 
EOT 


35 
36 
37 




EOT 


04 




EOT 


IE 




EOT((©) 


IF 




PN 
RS 

Upshift 
EOT((C)) 


19 t993 
lA C9A3 

IC C9C3 
IF 




EOT((g)) 


m 




EOT(©) 


> 04 . 




EOT((C)) 


1 ' ' ^ ,. 




Upshft 
EOT((C)) 


tcc:9c3 




Upshft 
EOT(®J 


ICC9C3 

IF 




RS 

EOT( (Q ) 






PN 
RS 

Upshft 

EOT(© 


19 

1A 

IF te 


* STOP 

A C 


FIGS 


m 




TpAuxOn 
EOT 


48 (49) 

CC93Da 




FIGS 
LF 


Cl83 38 

(08) 




FIGS 
LF 


Db3 38 
(08) 


34 
35 
36 
37 


52 
53 
54 
55 


56 
57 
58 
59 




CU3 


38 
39 
3A 
3B 






■ 






















































































38 
39 
3A 
3B 


56 

58 
59 


60 
61 
62 
63 




DC4 
NAK 

SUB 


3C 
3D 
36 

3F 




DC4 
NAK 

SUB 


14 
15 

lA 




NAK 
SUB 


3D 

OE 


/ 




(23) 


: 




m} 


/ 




m 




NAK 


< 15 - 




NAK 








(88) 






(^> 












iti: 


/ 




(37) 




X-Off 


(C9) (C9) 
(5C) (5D) 


/ 




(37) 


/ 




(2A) 


3C 
3D 
3E 
3F 


60 
61 
62 
63 


64 
65 
66 
67 




SP 


40 
41 
42 
43 




SP 


20 




SP 


1A 




SP 


01 




SP 


artml 




SP 


m 




SP 


40 




SP 


W^ 




SP 


01 Wl 




SP 


01 CS13 


\ 


SP 


0! DO 




SP 


^xmi 




SP 


04 1:243 




SP 


05 05 




SP 


04 D43 


SP 


04 C243 


40 
41 
42 
43 


64 
65 
66 
67 


68 
69 
70 
71 






44 

45 
46 
47 










































y>i/;/ 












/ 






































44 
45 
46 
47 


68 
69 
70 
71 



Figure 42. TCAM Internal and Device Codes (Part 1 of 4) 



*C9 and 21 ore valid EOT characters 
for both even parity and non parity 
trantmission. 



Appendix D: Internal and Transmission Code Charts 561 



Ref. 


Infernal S/360 


































IBM 2260 (Remote) /2265 








2741 1 


AT&T 83B3 








1 


WT Telegraph 1 


EBCDIC 


Ref. 


Code (EBCDIC) 


USASCII 


6-Bit Transcode 


IBM 1030 


IBM 1050 


IBM 1060 


2260/2265 


1053 


IBM 2740 


BCD 


EBCD 


Correspondence 1 


W U 115A 


AT&T TWX 


ITA2 


^bLJ 


Oiaracfer 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


<bde 
<H»x) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Cpde 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


1 


Co4e.; 
(Hex), 


Character 


(Hex) 


Character 


Code 

(Hex) 


Character 


0^. -, 


character 1 


CbiJe 
(Hex) 


Character 1 


Code 
(Hex) 


Code 
(Hex) 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


n 


12 


13 


14 


15 


16 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


.31 


32 


. ^V 


34 


35 


36 


37 


38 


39 


40 


41 


-42'' - 


43 


44 


45 


46 


47 


48 


49 


72 
73 

74 
75 


<? 




48 

4a' 
4B 


C 




5B 
2E 






OB 




® EOFC 


76 


<; 


® 


AO 
76 




® 


(76) 






1 
4E 






m 
m 


<f 


® 


AO 
76 


C 


® 


AO 
76 N 


<? 


® 


76 






A6 [C5] 






27 


] 




00 ;\ B0 

74^1:^75 






' 27 






21 


48 
49 
4A 
4B 


71 
73 
74 
75 


76 
77 
78 
79 


< 
( 

+ 

1 




4C 
4D 
4E 
4F 


< 

( 
+ 

1 




3C 
28 
2B 
21 


n 




OC 








< 

( 

+ 
1 




'84 
93 
El 
B7 








< 
( 

+ 

1 




5C 
48 
4B 
FE 


< 
( 

+ 

1 




(sq i 

(48) 

m 

: (FE) 


< 
( 

+ 

1 


® 


84 
93 
El 
07 


( 
+ 

± 


EOA(®) 


93 
El 
96 


> 

( 

+ 

1 


© 


"— ■"""; 

84 

93 ■' 
t\ 
B7 


( 

+ 

[ ± 




80 
96 
E4 
82 


<A l/2c 




3E 


< 
( 

+ 

t 




14 <v:i5 
D4:t;>'D$ 

70/.^;^; 70 


( 

+ 




3e 

31 


( 
+ 




35 
38 


4C 
4D 
4E 
4F 


76 
77 
78 
79 


80 
81 
82 
83 


& 




50 
51 
52 
53 


& 




26 


& 




10 


&s ■*•« 




61 


& 




.61 


+ 




m 


& 




46 


& 




(46) 


& 




61 


& 




61 


& 




61 .. 


& 




. 80 


& 




20 


& 




65 - /65 














50 
51 
52 
53 


80 
81 
82 
83 


84 
85 
86 
87 






54 
55 
56 
57 




























































', 


















.'*T,\ 














54 
55 
56 
57 


84 
85 
86 
87 


88 
89 
90 
91 


1 
$ 




58 
59 
5k 
5B 


I 




5D 
24 


$ 




IB 


$ 




57 


1 
$ 




S7 


$ 




m 


$ 




44 


$ 




(44) 


1 

$ 




07 
57 


1 
$ 




D7 
57 


1 
$ 




D7 
57 


1 
$ 




40' 
90 


2a lAc 
$ 




36 
32 


1 

$ 




84 - '"as 

24 25 














58 
59 
5A 
5B 


88 
89 
90 
91 


92 
93 
94 
95 


) 




5C 

.50 

5E 

5F 


) 




2A 
29 
3B 

5E 






1C 








) 

; 


® 


90 
95 
87 
F6 








) 




4A 
49 
50 
FC 


) 




' (4A) 
(49) 
(58) 

\ (FC)> 


) 


® 


90 
95 
87 
F6- 


) 
o 




90 
95 
87 

84 


) 
—I 


® 


90 , 

95 . - 
87, • 


* 

) 




8E 
93 
60 






29 
2F 


) 




55^^.55* 
95 ^ 95 
DD ;\ DP 


) 




29 


) 




29 


5C 
5D 
5E 
5F 


92 
93 
94 
95 


96 
97 
98 
99 


/ 




' 60 
6] 
62 
63 


/ 




2D 
2F 


/ 




20 
21^ 


/ 


® 


40 
23 


/ 


(S) 


40 
23 


/ 


® 


(40) 
23 


/ 




4D 
. 4F 


/ 




(4D) 
(4F), 


/ 


® 


40 
.23 


/ 


® 


' ' A^ 

23 


/ 


® 


40 * 
23 


/ 




71 ' 

70 


/ 




^' ' 

37 


/ 




B4"" ' ^05 
F5"'r^ F5 


/ 




38 

37 


/ 




30 < 
2A 


60 
61 
62 
63 


96 
97 
98 
99 


100 
101 
102 
103 






64 
65 
66 
67 














































































\';>"/ 














64 
65 
66 
67 


100 
101 
102 
103 


104 
105 
106 
107 




EOM 


68 
69 
6A 


1 




7C 
2C 






2B 




© 


37 






37 






(37) 


- 


EOM 


41 
AC 


I 




(41) 
(40 




® 


37 




© 


37 [07] 




© 


37; ' 






m se 


'A '^ 




26 






35 '5 ,35 






26 






26 


68 
69 
6A 
6B 


104 
105 
106 
107 


108 
109 
110 
111 


% 

> 
? 




6C 
6D 
6E 
6F 


% 

> 
? 




25 
5F 
3E 
3F 


% 




2C 








% 

> 

? 


® 


SB 
00 
8€ 
A3 








% 

> 
? 




45 
BF 

5F 


% 

> 
? 




. (45) ^^ 
(BF), , 

, (5£)7. 

(5F); 


% 


® 


88 
CO 


% 
'? 


® 


80 
CO 
8E 
A3 


% 

_ 

> 
? 


® 


80 
CO 

81- ~ 
A3 


% 


? 




■as'" 
- m 

CO 

FO 


\ 5/8e 




;'33v> 


% 

> 

? 




AS -5 AS 

FA ,-' , n 

70 70 

FC FD 


? 




33 


? 




25 


6C 
6D 
6E 
6F 


108 
109 
110 
111 


112 
113 
114 
115 






70 
71 
72 
73 






, 


































































-f:>i' " 












' 








70 
71 
72 
73 


112 
113 
114 
115 


116 
117 
118 
119 






74 
7$ 
76 
77 




























































, :/ 






•- '"->'»' 






^' 




















74 
75 
76 
77 


116 
117 
118 
119 


120 
121 
122 
123 


# 


EOA 


^|3 
7A 
7B 


c 

i 




60 
3A 
23 


# 




38 


'S =H 


EOA( ® ) 


\6 


# 


EOA((§) ) 


8B 

'J6 ' " 


# 


EOA( ® ) 


16 


'* 




5A 
43 


# 




(5A> : 
(43) 


# 


EOA(®) 


88 


# 


EOA(®) 




# 


EOA( ®) 


16 


: 
If 






: 1/8 

A C 


CR 




c 

# 




00.4'^ ^,00 
5C;'''^'5D 






' ''^2t'^ 


: 




23 ^ 


78 
79 
7k 
7B 


120 
121 
122 
123 


124 
125 
126 
127 


@ 




70 
7D 
7B 
7F 


@ 




40 
27 
30 
22 


@ 




3C 


@ 1 
S H 


i 


(20) 


@ 


EOA((D) ) 


96 




Add 


(20) 


@ 




^ EO 

47 

• .SB 


@ 




JEO): 


@ 


EOA 


20 

', . m: % 

82 

' - >96 ■ ' 


@ 






@ 


EOA 


20 

$2 
96 


^ 




^"w :"' 

' '-49 
64 
.C9 


'a 


Bell, 


, 31, 


f 




BO;:;^,0O 
4A::p:M 


= 




' 34 

'2f, 


= 




' -> ^ 34> 


7C 
7D 
7E 
7F 


124 
125 
126 
127 


128 
129 
130 
131 


a 
b 

c 




82 
83 


a 
b 

c 




6\ 
63 


A 
C 




(01) 
(02) 
(03) 


A 
B 
C 




(64) 


a 
b 

c 




62 


A 
B 
C 




(62) 
(64) 

m 


A 
B 
C 




(A3). 


A 
B 
C 






a 
b 
c 




' .6^ ' ' 

• ' ' ;64 ^ 
; 17- ^' 


a 
b 

c 




62 


a 
b 
c 




62 

64 " 
67 


a 
b 

c 




\0 ' 

V37 : 


A 
B 
C 






A 
B 
C 




(42);. (43) 


A 
B 
C 




in} 


A 
B 
C 




(18) 
03) 
(OH) 


80 
81 
82 
83 


128 
129 
130 
131 


132 
133 
134 
135 


d 

e 
f 
9 




84 
85 
86 
S7 


d 

e 
f 
9 




64 
65 
66 
67 


D 
E 
F 
G 




(04) 
(05) 
(06) 

m 


D 
E 
F 
G 




mi 
m) 

(6D) 


d 

e 
f 
9 




6t\ 
6(> 

:6i": 


D 

E 
F 
G 




(68) 

Am 

(6D) 

m 


D 

E 
F 
G 




/ (^4) 

''''r(^)": 


D 
E 
F 
G 




(A6) 
(AT) ; 


d 

e 
f 
9 




. .6$ 
60 
6D 

6E /> 


d 

e 
f 
9 




6a 

68 

m 

61 


d 
e 

f 
9 




6n 

60 
60 
6£ 


d 

e 
f 
9 




:'^:"'2A"'. 
. <6y' 

62 , 


D 
E 
F 
G 




<to) 


D 
E 
F 
G 




(A3); (A3) 
(63) 163) 

mnm 



E 
F 
G 




(10) 

(16) 

. (08) 


D 
E 
F 
G 




m 
m 

(U) 
(08) 


84 
85 
86 
87 


132 
133 
134 
135 


136 
137 
138 
139 


h 

i 




88 
8^ 

aA 

80 


h 




68 
69 


H 
1 




(08) 
(09) 


H 




m 

(?3> 


h 




70 

>3''', 


H 
1 




(70) 
(73) 


H 
1 






H 




>9). ; 


h 

i 




70 

y:;7r ,; 


h 




"' '70 

73 


h 




70 

73,;, ,- 


h 

i 




'"4C , 


H 
1 




(0C> 


H 

1 




(12^; (13) 
mm) 


H 




mi 

/ (OQ 


H 




(05) 


88 
89 
8A 
8B 


136 
137 
138 
139 


140 
141 
142 
143 






8C 

m 
ae 












^ 






























. ; ' 






^^llk^k.^ 
























-/--'^! ' 




















8C 
8D 
8E 
8F 


140 
141 
142 
143 



Figure 42. TCAM Internal and Device Codes (Part 2 of 4) 



Appendix D: Internal and Transmission Code Charts 563 



Ref. 


Internal S/360 
Code (EBCDIC) 


Code 


USASCII 


Os<le 


6-Bit Transcode 


Code 


IBM 1030 


IBM 1050 




IBM 1060 
1 


IBM 2260 (Rerr,ote)/2265 
2260/2265 1053 


IBM 2740 


BCD 


2741 

EBCD i 


Correspondence 


AT&T83B3 
W U 1 15A 


AT&TTWX 


WT Telegraph 
ITA2 1 ZSC3 


EBCDIC 

Code 

(Hex) 


Re-. 


Graphic 


Control 


(Hex) 


Graphic 


Control 


(He;<) 


Graphic 


Control 


(Hen) 


Graphic 


Control 


(Hex) 


Graphic 


racter 
Control 


(Hex) 


Cha 
Graphic 


acter 
Control 


Code 
(Hex) 


Character 
Graphic Control 


Code 
(Hex) 


Character 
Graphic Contiol 


Code 

(H»x) 


Cho 
Graphic 


actsr 
Control 


Code 
(Hex) 


Ch 
Graphic 


Kacter 

Control 


Code 
(He>«) 


Char 
Graphic 
31 


acter 
Control 


Code 

(Hex) 


Character 
Graphic Control 


Code 
(Hex) 


Cho 
Graphic 


racter 
Control 


Code 
(Hex) 


Character 
Graphic Control 


Code 
(Hex) 


Chore 
Graphic 


cter 
Control 


Code 
(Hex) 


Character 
Graphic Control 


Code 
(Hex) 


1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


17 


18 


19 


20 


21 


22 


23 


'" ' 24 


25 


26 


27 


28 


29 


30 


32 


33 


34 


35 


' 36 


37 


38 


39 


40 


41 


42 


43 


44 


. 45 


46 


47 


48 


49 


144 






90 
































































































145 
146 
147 


i 
k 

1 




91 
92 
93 


i 

k 
1 




6A 
6B 
6C 


J 
K 
L 




(H) 

(12) 
(13) 


J 
K 

L 




(43) 

(45) 
(46) 


i 

k 
1 




- 43 
45 
46 


J 

K 

L 




(43) 
(45) 
(46) 


J 
K 

L 




(AA) 
(AB) 
(AC) 


J 
K 

L 




(AA) 
(AB). 
(AC) 


i 

k 

1 




43 
45 
46 


i 

k 

1 




43' 
45 
46 


i 

k 
1 




43 

45 
46 


i 

k 
1 




61 
2C 
31 


J 

K 

L 




(lA) ' 

(IE) 

(09) 


J 
K 
L 




(53) (53) 
(D2) (D3) 
(33) (33) 


J 

K 

L 




(lA) 
(IE) 
(09) 


J 
K 

L 




(lA) 
(IE) 
(09) 


90 
91 
92 
93 


144 
145 
146 
147 


148 
149 


m 




94 

95 


n 




60 

6E 


M 

N 




(M) 
(15) 


M 
N 




(49) 
(4A) 


n 




49 
4A 


M 
N 




(49) 
(4A) 


M 
N 




(AD) 
(AE) 
(AF) ^ 
(80) 


M 
N 




(AD) 

im 

(80) 


m 




49 
4A 

4C 

4F 


m 




49 
4A 
4C 
4F 


m 




49 


m 




43 


M 




(07) 


M 




(B2) (83) 


M 




(07) 


M 




(07) 


94 


148 


150 
151 


o 

P 




96 
97 


P 




6F 
70 


O 
P 




(16) 
(17) 


O 
P 




(4C) 

(4F) 


o 
P 




4C 

4F 


O 
P 




(4C) 

m 


O 
P 




o 

P 




o 
P 




P 




P 




4A 
4C 
4F 


n 
P 




25 
51 

• 68 


N 
O 

P 




(06) 
(03) 
(OD) 


N 
O 
P 




(72) (73) 
(F3) (F3) 
(OA) (08)- 


N 
O 
P 




(06) 
(03) 
(00) 


N 
O 
P 




(06) 
(03) 
(00) 


95 
96 
97 


149 
150 
151 


152 
153 
154 


q 

r 




98 
99 
9A 


q 




71 
72 


Q 
R 




(18) 
(19) 


Q 

R 




(51) 
(52) 


q 

r 




51 
52' 


Q 

R 




(51) 
(52) 


Q 
R 




(B1) 
(82) 


Q 
R 




(81) 
(82) 


q 




5\ 
52 


q 




51 
52 


q 




51 
52 


q 

r 




60 
, 4A 


Q 

R 




(ID) 
(OA) 


Q 

R 




(8B) (8B) 
(48) (48) 


Q 

R 




(ID) 
(OA) 


Q 
R 




(ID) 
(OA) 


98 
99 


152 
153 


155 






9B 




























































































9A 
9B 


154 
155 


156 






9C 
























































r 








































157 






9D 




























































































9C 


156 


158 






9E 




























































































9D 


157 


159 






9F 




























































































9E 
9F 


158 
159 


160 






AO 
































































































16) 






Al^ 


-^ 




7E 






















































































AO 


160 


162 
163 


i 
t 




A2 
A3 


i 
t 




73 
74 


s 

T 




(22) 
(23) 


S 
T 




(25) 
(26) 


s 
t 




25 
26 


S 

T 




(25) 
(26) 


S 
T 




(B3) 
(84) 


S 

T 




(84) , 


s 

t 




25 
~ 26 


5 
t 




25 
26 


s 
t 




25 

26 


s 




52 
20 


s 

T 




(14) 
(01) 


S 
T 




(CA) (CB) 
(28) (2B) 


s 

T 




(14) 
(01) 


S 
T 




(14) 
(01) - 


AI 
A2 
A3 


161 
162 
163 


164 
165 
166 
167 


w 




A4 
A5 
A6 
A7 


r 




75 
76 
77 
78 


U 
V 

w 

X 




(24) 
(25) 
(26) 
(27) 


U 
V 
W 
X 




(29) 
(2A) 
(2C) 
(2F) 


u 

X 




29 

2A 
2C 

-2f 


u 

V 

w 

X 




(29) 

,(2A) 
(2C) 
<2F) 


u 

V 
W 
X 




(85) 
(B6) 
(B7) 
(B8) 


U 
V 

w 

X 




im - 


w 




. ' ' 29- 
^ - 2A 
,„ 2C 
2F ' 


r 




29 

2A 

' 2C 

2? 


r 




29 
2A 
2C 
2F 


u 

X 




26 

' 46 

57 

23 


U 
V 

w 

X 




(1C) 
(OF) 
(19) 
(17) 


U 
V 

w 

X 




(AA) (AB) 
(6A) (68) 
(EB) (EB) 
(IB) (18) 


U 
V 

w 

X 




(IC) 
(OF) 
(19) 
(17) 


U 
V 

w 

X 




(IC) 
(OF) 
(19) 

(17) 


A4 
A5 
A6 
A7 


164 
165 
166 
167 


168 
169 
170 


y 

z 




A8 
A9 
AA 


y 

z 




79 
7A 


Y 

z 




(28) 
(29) 


Y 

Z 




(31) 
(32). 


y 

z 




31 
32 


Y 
Z 




(3T) 
(32) 


Y 

Z 




(B9) 
(BA) 


Y 

z 




K 


y 

z 




31 

~Z2 


y 
y 




31 

32 


y 

z 




31 
32 


y 

z 




73 
15 


Y 

z 




(15) 
{11} 


Y 

z 




(9A) (98) 
(5A) (5B) 


Y 

z 




(15) 
(H) 


Y 

z 




(15) 
(11) 


A8 
A9 


168 
169 


171 






AB 




























































































AA 
AB 


170 
171 


172 






,AC 

































































































173 






AD 




























































































AC 


172 


174 






AE 




























































































AD 


173 


175 






AF 




























































































AE 
AF 


174 

175 


176 






BO 
































































































17/ 






81 




























































































BO 


176 


178 






B2 


















'\ 






























. ' 












































Bl 


177 


179 






B3 




























































































B2 
B3 


178 
179 


180 






B4 
































































































181 






B5 


















'■ 










































































B4 


180 


182 






B6 
















































.,? 












































B5 


181 


183 






B7 




























































































B6 
B7 


182 
183 


184 






sa 
































































































185 






89 
















































, ■■:■'■■'< 












































B8 


184 


186 






BA 














































































' 














B9 


185 


187 






SB 
















































->'f.: 












































BA 
BB 


186 
187 


188 






BC 
































































































189 






BO 








































































« 




















BC 


188 


190 






BE 




























































































BD 


189 


191 






BF 




























































































BE 
BF 


'90 
191 


192 
193 
194 
195 


A 
B 
C 


PZ 


CO 
CI 
C2 

C3 


A 
B 
C 




• 7B 

43 




A 




01 


A 




62 


A 


PZ 


75 
E2 


A 


Restore 


(75) 
62 


A 




A1 


A 




, (A1) , 


A 




'•E2' 


A 




* £2 


A 




£2 


A 




CF 


A 




18 


A 




82 83 


A 




18 


A 




18 • 


CO 
CI 


192 
193 






C 










64 


B 




E4 


B 




64 


B 




A2 


B 




:(A2) 


B 




>..64' 


B 




E4 ■ 


B 




E4 


B 




87 


B 




13 ' 


B 




^42 43 


B 




^ 13 


B 




13 


C2 


194 


1 












67 


C 




E7 


C 




(67) 


C 




A3 


C 




^3) 


C 




• £7 


c 




U 


C 




£7 


C 




^ Af 


C 




m 


C 




C3 C3 


C 




: OE 


C 




OE 


C3 


195 


196 
197 
198 
199 


D 

E 
F 
G 




C4 

, C5 

C6 

C7 


D 
E 
F 
G 




44 
45 
46 

47 


D 
E 
F 
G 




04 

05 

06 

■ 07 


D 
E 
F 
G 




68 
6B 
60 

6E 


D 

E 
F 
G 




£8 
EB 
ED 

EE 


D 
E 
F 
G 




(68) 
68 
60 

(6E) 


D 

E 
F 
G 




A4 
A5 
A6 
A7 


D 

E 
F 
G 




(A4) 

CA6) 


D 
E 
F 
G 




■ ' £8 . . 


D 
E 

F 
G 




68 

m "' 

£0 


D 
E 
F 
G 




,£8 
18 

m 

££ 


D 

E 
F 
G 




.AA 
A9 
£7 
E2 


D 
E 
F 
G 




it 
to 

16 

OB 


D 
E 
F 
G 




22 23 
A3 A3 
63 63 

£2 £3 


D 
E 
F 
G 




12 
10 
16 
08 


D 
E 
F 
G 




12 

10 
16 

08 


C4 
C5 
C6 
C7 


'96 
197 
198 
199 


200 
201 


H 
1 




C8 
C9 
CA 


H 
1 




40 

49 


H 




08 
09 


H 




70 
73 


H 




FO 
F3 


H 




<?0) 


H 




A8 


H 




(A8) 


H 




< FO 


H 




FO 


H 




m 


H 




82 


H 




05 


H 




12 13 


H 




, 05 


H 




05 


ca 


200 


202 
































A9 


1 




CA9) 


1 




' n- 


1 




f3 > 


1 




n 


1 




CC 


1 




OC 


1 




93 ^3 


1 




. OC 


1 




OC 


C9 


201 


203 






CB 










































'.\ 


















































CA 
CB 


202 
203 


204 






CC 
































































































205 






CD 




























































































CC 


204 


206 






CE 




























































































CD 


205 


207 






CF 


\ 




iSC) 






















































































CE 
CF 


206 
207 


208 
209 
210 
211 




MZ 


DO 


> 




7D 
















MZ 


54 




Message 


(54) 


















\ . _ 












































DO 


208 


J 
K 

L 




01 
02 
03 


J 




4A, 
4B 
4C 


J 




n 


J 




43 


J 




C3 


J 




43 


J 




AA 


J 




(AA) 


J 




'iCZ 


J 




C3 


J 




C3 


J 




£( 


J 




1A 


J 




53 53 


J 




lA 


J 




)A 


Dl 


209 




L 




L 




12 
13 


K 




45 


K 




C5. 


K 




- 45 


K 




A8 


K 




. iA8) 


K 




"' C5, . 


K 




C5 


K 




C5 


K 




AC 


K 




IE 


K 




D2 D3 


K 




IB 


K 




IE 


D2 


210 












46 


L 




C6 


L 




(46) 


L 




AC 


L 




(AC) 


L 




C6 


L 




C6 


L 




C6 


L 




81 


L 




0^ . 


L 




33 33 


L 




09 


L 




09 


D3 


211 


212 
213 
214 
215 


M 
N 
O 




04 
05 
D6 
07 


M 




40 

4£ 


M 




14 


M 




49 


M 




C9 . 


M 




m 


M 




AD 


M 




(AO) 


M 




'- C9 '' 


M 




C9 


M 




C9 


M 




^ C3 


M 




07 


M 




82 83 


M 




07 


M 




07 


D4 


212 












15 


N 




4A 


N 




CA 


N 




(4A) 


N 




AE 


N 




<AE) 


N 




/CA' ' 


N 




CA 


N 




CA 


N 




A5 


N 




06 


N 




72 73 


N 




06 


N 




06 


D5 


213 




P 




w 


P 




16 


o 




4C 


o 




CC 


O 




m) 


O 




AF. 


O 




MY- 


o 




\<X 


O 




< ' CC 


o 




CC 


O 




= 01 > 


O 




03 


O 




F3 F3 


O 




03 


O 




03 


D6 


214 


' 












4F 


P 




CF 


P 




m 


P 




80 


P 




Km 


P 




:<^:.. 


P 




CF 


P 




' CF 


P 




' m 


P 




00 


P 




OA 08 


P 




OD 


P 




00 


D7 


215 






2, 


No EBCDK 


Z character h 


js been assig 


led to 



























































































this location (161/3,161/4). 



Figure 42. TCAM Internal and Device Codes (Part 3 of 4) 



Appendix I): Internal and Transmission Code Charts 565 





Internal S/360 


1 
































IBM 2260 (Remote) /2265 








2741 


AT&T 83B3 










WT Telegraph 


EBCDIC 


Ref. 




Code (EBCDIC) 


USASCII 


6-Bit Transcode 


IBM 1030 


IBM 1050 


IBM 1060 


2260/2265 


1053 


IBM 2740 


BCD 


EBCD 


Correspondence 


W U 1 15A 


AT&T TWX 


ITA2 


ZSC3 




Character ] 


Code 
(Hex) 


Character 


Code 

(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
<Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Character 


Code 
(Hex) 


Code 
(Hex) 




Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Graphic 


Control 


Ref. 


1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


]5 


16 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


31 


32 


33 


34 


35 


36 


37 


38 


39 


40 


41 


42 


43 


44 


45 


46 


47 


48 


49 


216 
217 
218 
219 


Q 
R 




D8 
D9 
DA 
DB 


Q 
R 




51 
52 


Q 
R 




18 
19 


Q 
R 




51 
52 


Q 
R 




D2 


Q 
R 




(51) 
(52) 


Q 
R 




Bl 
B2 


Q 

R 




(Bl) 
(B2) 


Q 
R 




D1 
02 


Q 
R 




D2 


Q 
R 




Dl 
D2 


Q 
R 




ED 
CA 


Q 
R 




ID 
OA 


Q 
R 




8B 8B 
4B 4B 


Q 
R 




ID 
OA 


Q 
R 




ID 
OA 


D8 
D9 
DA 
DB 


216 
217 
218 
219 


220 
221 
222 
223 






DC 
DD 
DE 
DF 




























































































DC 
DD 
DE 
DF 


220 
221 
222 
223 


224 
225 
226 
227 


S 

T 


RM 


E2 
E3 


\ 
S 

T 




5C 
53 

54 


S 

T 




22 
23 


S 

T 




25 
26 


t 
S 
T 


RM 


34 

A5, 
A6 


S 

T 




(25) 
" (26) 


S 

T 




B3 

B4 . 


S 

T 




(B3) 
(B4) 


S 
T 




A5 
A6 


S 
T 




A5 
A6 


S 
T 




A5 
A6 


S 

T 




D2 
AO 


/ 
S 
T 




14 
01 


\ 

s 

T 




3A 3B 
CA CB 
2B 2B 


s 

T 




14 
01 


S 

T 




14 
01 


EO 
El 
E2 
E3 


224 
225 
226 
227 


228 
229 
230 
231 


U 
V 

w 

X 




£4 
E5 
E6 
E7 


U 
V 

w 

X 




55 
56 

57 
58 


U 
V 

w 

X 




24 
25 
26 
27 


U 
V 

w 

X 




29 
2A 
2C 
2F 


U 
V 
W 
X 




A9 
AA 
AC 
AF 


U 
V 

w 

X 




(29) 
(2A) 
(2C) 
(2F) 


u 

V 

w 

X 




B5 
B6 
B7 
B8 


u 

V 

w 

X 




(B5) 
(B6) 
(B7) 
(68) 


U 
V 
W 
X 




A9 
AA 
AC 
AF 


u 

V 
W 
X 




A9 
AA 
AC 
AF 


U 
V 

w 

X 




A9 
AA 
AC 
AF 


U 
V 
W 
X 




A6 

a 

D7 
A3 


u 

V 

w 

X 




IC 
OF 
19 
17 


U 
V 
W 
X 




AA AB 
6A 6B 
EB EB 
IB IB 


U 
V 
W 
X 




IC 
OF 
19 
17 


U 
V 
W 
X 




IC 
OF 
19 
17 


E4 
E5 
E6 
E7 


228 
229 
230 
231 


232 
233 

234 
235 


Y 
Z 




£8 
£9 
EA 
EB 


Y 

z 




59 
5A 


Y 

z 




28 
29 


Y 

z 




31 

32 


Y 

z 




Bl 
B2 


Y 

z 




(31) 
(32) 


Y 

z 




B9 
BA 


Y 

z 




(B9) 
(BA) - 


Y 

z 




Bl 

S2 


Y 

z 




61 
B2 


Y 

z 




Bl 
B2 


Y 

Z 




F3 

95 


Y 

z 




f5 
11 


Y 

z 




9A 9B 
5A 5B 


Y 

Z 




15 
11 


Y 

Z 




15 
11 


E8 
E9 
EA 
EB 


232 
233 
234 
235 


236 
237 
238 
239 






EC 
ED 
EE 
EF 




























































































EC 
ED 
EE 
EF 


236 
237 
238 
239 


240 
241 
242 
243 



1 

2 
3 




FO 
Fl 
F2 
F3 




1 

2 
3 




30 
31 
32 
33 




1 

2 

3 




30 
31 
32 
33 


04 

1 

2 

3 




(15) [20] 
02 
04 
07 




1 

2 
3 




15 
02 
04 
07 




1 

2 

3 




. 15 
02- 
04 
07 




1 

2 

3 




50 
5\ 
52 
53 




1 

2 

3 




(50) 
(51) 
(52) 
(53) 




1 

2 
3 




15 
02 
04 
07 




1 

2 

3 




15 
02 
04 
07 




1 

2 
3 




15 
02 
04 
07 




i] 

2 
3 




13 
02 
04 
07 




1 

2 
3 




2D 
3D 
3^ 

30 




1 

2 

3 




OC OD 
8D 8D 
4D 40 
CC CD 




1 

,2 

3 




2D 
3D 
39 
30 




1 

2 
3 




2B 
3C 
3A 
39 


FO 
F1 
F2 
F3 


240 
241 
242 

243 


244 
24f. 
2-^6 
247 


4 
5 
6 

7 




F4 

. F5 
F6 
F7 


4 
5 
6 
7 




34 
35 
36 
37 


4 
5 
6 

7 




34 
35 
36 
37 


4 
5 
6 

7 




08 
OB 
OD 
OE 


4 
5 
6 

7 




08 
OB 
OD 
OE 


4 
5 
6 
7 




08 
OB 
OD 
OE 


4 
5 
6 
7 




54 
55 
56 
57 


4 
5 
6 
7 




(54) 
(55) 
(56) 
(57) 


4 
5 
6 

7 




08 
OB 
OD 
OE 


4 
5 
6 
7 




08 
OB 
OD 
OE 


4 
5 
6 
7 




08 
OB 
OD 
OE 


4 
5 
6 
7 




10 
08 
OD 
OS 


4 
5 
6 
7 




2A 
21 
35 
3C 


4 
5 
6 
7 




2D 2D 
AC AD 
6C 6D 
ED ED 


4 
5 
6 
7 




2A 
21 

35 
3C 


4 
5 
6 
7 




36 

35 
33 
27 


F4 
F5 
F6 
F7 


244 
243 
246 
247 


248 
249 
250 
251 


8 
9 




F8 

. F9 

FA 

FB 


8 
9 




38 
39 


8 
9 




38 
39 


8 
9 




10 
13 


8 
9 




10 
13 


8 
9 




10 
13 


8 
9 




58 
59 


8 
9 




(58) 
(59) 


8 
9 




10 
13 . 


8 
9 




10 
13 


8 
9 




10 
13 


8 
9 


EOA 


OE 
16 


8 
9 




2C 

23 


8 
9 




ID ID 
9C 90 


8 
9 




2C 
23 


8 
9 




2E 
2D 


F8 
F9 
FA 
FB 


248 
249 
250 
251 


252 
253 
254 

255 






FC ' 
FD 

n 

FF 




























































































FC 
FD 
FE 
FF 


252 
253 
254 

255 



3. No EBCDIC character has been 

assigned to this location (225/3,225/37), 
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S/360 


Graphic 


Control 


Byfe (hex) 






00 




NUL 


01 




SOH 


02 




STX 


03 




ETX 


04 




PF 


05 




HT 


06 




LC 


07 




DEL 


08 






09 






OA 




SMM 


OB 




VT 


OC 




FF 


OD 




CR 


OE 




SO 


OF 




SI 


10 




DLE 


11 




DCl 


12 




DC2, 


13 




TM 


14 




RES 


15 




NL 


16 




BS 


17 




IL 


18 




CAN 


19 




EM 


lA 




CC 


IB 




CUl 


IC 




IFS 


ID 




IGS 


IE 




IRS 


'F 




lUS 


20 




DS 


21 




SOS 


22 




FS 


23 






24 




BYP 


25 




LF 


26 




ETB (EOB) 


27 




ESC (PRE) 


28 






29 






2A 




SM 


2B 




CU2 


2C 






2D 




ENQ 


2E 




ACK 


2F 




BEL 


30 






31 






32 




SYN 


33 






34 




PN 


35 




RS 


36 




UC 


37 




EOT 


38 






39 






3A 






3B 




CU3 


3C 




DC4 


3D 




NAK 


3E 






3F 




SUB 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 




SP 


44 
45 
46 
47 






48 
49 
4A 
4B 


4 




4C 
4D 
4E 
4F 


< 

( 

+ 
1 




50 
51 
52 
53 


& 




54 
55 
56 
57 






58 
59 
5A 
5B 


! 
$ 




5C 
5D 
5E 
5F 


) 
— 1 




60 
61 
62 
63 


/ 




64 
65 
66 
67 






68 
69 
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Figure 43. IBM S/360 Internal Code (EBCDIC) 
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Figure 44. USASCII Code 
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Figure 45. Hexadecimal Equivalents for 6-bit Transcode 
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Note 1 : The IBM 1031 Input Station transmits the numeric as an A bit only; the IBM 1033 Printer receives a numeric as C-8-2 and an @ as an A bit. 

Note 2: The IBM 1031 Input Station cannot transmit the following characters as data: % * . ^ x(an EOFC is transmitted and punched by the IBM 1034 Card Punch). 

Figure 46. Line Code for IBM 1030 Data Collection System 
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Figure 47. Line Code for IBM 1050 Data Communication System 
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Figure 48. Line Code for IBM 1060 Data Communication System 
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33 



34 
35 
36 
37 



38 
39 
3A 
3B 



3C 
3D 
3E 
3F 



2260/2265 
Graphic G>nlTol 



STX 

ETX 



EOT 
ACK 



1053 
Graphic Gjntrol 



STX 

ETX 



EOT 
ACK 



S/360 Byte 


2260/2265 


1053 


(hex) 


Graphic 


Gsntrol 


Graphic 


Control 


40 




SP 




SP 


41 


■■ 


EOM 


1 




42 


1 


CHECK 


•' 




43 


# 




1 




44 


$ 




$ 




45 


% 




% 




46 


& 




& 




47 


• 




' 




48 


( 




( 




49 


) 




) 




4A 










4B 


+ 




+ 




4C 


, 




, 




4D 


- 




- 




4E 










4F 


/ 




/ 




50 












51 


1 




1 




52 


2 




2 




53 


3 




3 




54 


4 




4 




55 


5 




5 




56 


6 




6 




57 


7 




7 




58 


8 




8 




59 


9 




9 




5A 










5B 


; 




; 




5C 


< 




< 




5D 


= 




= 




5E 


> 




> 




5F 


? 




? 




60 










61 










62 










63 










64 










65 










66 










67 










68 










69 










6A 










6B 










6C 










6D 










6E 










6F 










70 










71 










72 










73 










74 










75 










76 










77 










78 










79 










7A 










7B 










7C 










7D 










7E 










7F 











Figure 49. Line Codes for IBM 2260 (Remote)/2265 Display Complexes and IBM 1053 Printer (Part 1 of 2) 



Appendix D: Internal and Transmission Code Charts 575 



S/360 Byte 


2260/2265 


1053 


(hex) 


Graphic 


Control 


Graphic 


Control 


80 










81 










82 










83 










84 










85 










86 










87 










88 










89 










8A 










8B 










8C 










8D 










8E 










8F 










90 










91 










92 










93 










94 










95 










96 










97 










98 










99 










9A 










98 










9C 










9D 










9E 










9F 










AO 










Al 


A 




A 




A2 


B 




B 




A3 


C 




C 




A4 


D 




D 




A5 


E 




E 




A6 


F 




F 




A7 


G 




G 




A8 


H 




H 




A9 


1 




1 




AA 


J 




J 




AB 


K 




K 




AC 


L 




L 




AD 


M 




M 




AE 


N 




N 




AF 


O 









BO 


P 




P 




Bl 


Q 




Q 




B2 


R 




R 




B3 


S 




S 




B4 


T 




T 




B5 


U 




U 




B6 


V 




V 




B7 


W 




w 




B8 


X 




X 




B9 


Y 




Y 




BA 


Z 




Z 




BB 










BC 










BD 


► 


SMI 


<? 




BE 










BF 


- 




- 





S/360 Byte 
(hex) 


2260/ 
Graphic 


'2265 

Control 


10 
Graphic 


53 

Control 


CO 
CI 
C2 
C3 










C4 
C5 
C6 
C7 










C8 
C9 
CA 
CB 










CC 
CD 
CE 
CF 










DO 
Dl 
D2 
D3 










D4 
D5 
D6 
D7 










D8 
D9 
DA 
DB 










DC 
DD 
DE 
DF 










EO 
El 
E2 
E3 


@ 




@ 




E4 
E5 
E6 
E7 










E8 
E9 
EA 
EB 










EC 
ED 
EE 
EF 










FO 
Fl 
F2 
F3 










F4 
F5 
F6 
F7 










F8 
F9 
FA 
FB 










FC 
FD 
FE 
FF 


1 




1 





Figure 49. Line Codes for IBM 2260 (Remote)/2265 Display Complexes and IBM 1053 Printer (Part 2 of 2) 
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IBM 2740 EBCD Code 



S/360 
Byte (hex) 


Graphic 


Control 


00 
01 
02 
03 


1 


SP 


04 
05 
06 
07 


2 

3 




08 
09 
OA 
OB 


4 
5 




OC 
OD 
OE 
OF 


6 

7 




10 
11 
12 
13 


8 
9 




14 
15 
16 
17 





EOA 


18 
19 
1A 
IB 






1C 
ID 
IE 
IF 




Upshift 
EOT 


20 
21 
22 
23 


@ 
/ 




24 
25 
26 
27 


s 
t 




28 
29 
2A 
2B 


u 

V 




2C 
2D 
2E 
2F 


w 

X 




30 
31 
32 
33 


y 

z 




34 
35 
36 
37 


/ 


© 


38 
39 
3A 
3B 




Index Attn 


3C 
3D 
3E 
3F 




EOB 

PRE 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 


i 


® 


44 
45 
46 
47 


k 

1 




48 
49 
4A 
4B 


m 
n 




4C 
4D 
4E 
4F 


o 

P 




50 
51 
52 
53 


q 

r 




54 
55 
56 
57 


$ 




58 
59 
5A 
5B 




NL 


5C 
5D 
5E 
5F 




BS 
IL 


60 
61 
62 
63 


& 

a 




64 
65 
66 
67 


b 

c 




68 
69 
6A 
6B 


d 

e 




6C 
6D 
6E 
6F 


f 

g 




70 
71 
72 
73 


h 

i 




74 
75 
76 
77 




® 


78 
79 
7k 
7B 




HT 


7C 
7D 
7E 
7F 




Dwnshft 
DEL 



S/360 
Byte (hex) 


Graphic 


Control 


80 
81 
82 
83 


= 


SP 


84 
85 
86 
87 


< 




88 
89 
8A 
8B 


% 




8C 
8D 
8E 
8F 


> 




90 
91 
92 
93 


( 




94 
95 
96 
97 


) 


EOA 


98 
99 
9A 
9B 






9C 
9D 
9E 
9F 




Upshift 


AO 
Al 
A2 
A3 


? 




A4 
A5 
A6 
A7 


S 
T 




A8 
A9 
AA 
AB 


U 
V 




AC 
AD 
AE 
AF 


W 
X 




BO 
B1 
B2 
83 


Y 

z 




B4 
B5 
B6 
B7 


1 


© 


B8 
B9 
BA 
BB 




Index Attn 


BC 
BD 
BE 
BF 




EOB 



S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 


J 


® 


C4 
C5 
C6 
C7 


K 
L 




C8 
C9 
CA 
CB 


M 
N 




CC 
CD 
CE 
CF 


O 
P 




DO 
Dl 
D2 
D3 


Q 
R 




D4 
D5 
D6 
D7 


1 




D8 
D9 
DA 
DB 




NL 


DC 
DD 
DE 
DF 




BS 
IL 


EO 
El 
E2 
E3 


+ 
A 




E4 
E5 
E6 
E7 


B 
C 




E8 
E9 
EA 
EB 


D 

E 




EC 
ED 
EE 
EF 


F 
G 




FO 
Fl 
F2 
F3 


H 

1 




F4 
F5 
F6 
F7 


- 


® 


F8 
F9 
FA 
FB 




HT 


FC 
FD 
FE 
FF 




Dwnshft 
DEL 



Figure 50. Line Code for IBM 2740 Communication Terminal 
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S/360 
Byte (hex) 


Graphic 


Control 


00 
01 
02 
03 


1 


SP 


04 
05 
06 
07 


2 

3 




08 
09 
OA 
OB 


4 
5 




OC 
OD 
OE 
OF 


6 
7 




10 
11 
12 
13 


8 
9 




14 
15 
16 
17 





EOA 


18 
19 
lA 
IB 






1C 
ID 
IE 
IF 




Upshift 
EOT 


20 
21 
22 
23 


@ 
/ 




24 
25 
26 
27 


s 
t 




28 
29 
2A 
2B 


u 

V 




2C 

2D 
2E 
2F 


w 

X 




30 
31 
32 
33 


z 




34 
35 
36 
37 




® 


38 
39 
3A 
3B 




BYP 
index Attn 


3C 
3D 
3E 
3F 




EOB 
PRE 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 


i 


% 


44 
45 
46 
47 


k 
1 




48 
49 
4A 
4B 


m 
n 




4C 
4D 
4E 
4F 


o 

P 




50 
51 
52 
53 


r 




54 
55 
56 
57 


$ 




58 
59 
5A 
5B 




RES 
LF-CR 


5C 
5D 
5E 
5F 




BS 
IL 


60 
61 
62 
63 


& 

a 




64 
65 
66 
67 


b 
c 




68 
69 
6A 
6B 


d 
e 




6C 
6D 
6E 
6F 


f 

g 




70 
71 
72 
73 


h 

i 




74 
75 
76 
77 




© 


78 
79 
7k 
7B 




HT 


7C 
7D 
7E 
7F 




Downshift 
DEL 



S/360 
Byte Oiex) 


Graphic 


Control 


80 
81 
82 
83 


= 


SP 


84 
85 
86 
87 







88 
89 
8A 
8B 


% 


(n) 


8C 
8D 
8E 
8F 


" 




90 
91 
92 
93 


( 




94 
95 
96 
97 


) 

+ 


EOA 


98 
99 
9A 
9B 






9C 
9D 
9E 
9F 




Upshift 


AO 
Al 
A2 
A3 


4 
? 




A4 
A5 
A6 
A7 


\ 




A8 
A9 
AA 
A8 


u 

V 




AC 
AD 
AE 
AF 


w 

X 




BO 
Bl 
B2 
B3 


Y 

z 




B4 
B5 
B6 
B7 




© 


B8 
B9 
BA 
BB 




Index Attn 


BC 
BD 
BE 
BF 




EOB 



S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 


J 


® 


C4 
C5 
C6 
C7 


K 
L 




C8 
C9 
CA 
CB 


M 
N 




CC 

CD 
CE 
CF 


O 
P 




DO 
D1 
D2 
D3 


Q 
R 




D4 
D5 
D6 
D7 


! 




D8 
D9 
DA 
DB 




RES 
LF-CR 


DC 
DD 
DE 
DF 




BS 
IL 


EO 
El 
E2 
E3 


+ 
A 




E4 
E5 
E6 
E7 


B 

c 




E8 
E9 
EA 
EB 


D 
E 




EC 
ED 
EE 
EF 


F 
G 




FO 
Fl 
F2 
F3 


H 
1 




F4 
F5 
F6 
F7 




© 


F8 
F9 
FA 
FB 




HT 


FC 
FD 
FE 
FF 




Downshift 
DEL 



Figure 51. Hexadecimal Equivalents for IBM 2741 (BCD) Communication Terminal 
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S/360 
Byte (hex) 


Graphic 


Control 


00 
01 
02 
03 


1 


SP 


04 
05 
06 
07 


2 
3 




08 
09 
OA 
OB 


4 
5 




OC 
OD 
OE 
OF 


6 

7 




10 
11 
12 
13 


8 
9 




14 
15 
16 
17 





EGA 


18 
19 
lA 
IB 




RS 


IC 
ID 
IE 
IF 




UC 
EGT 


20 
21 
22 
23 


/ 




24 
25 
26 
27 


s 




28 
29 
2A 
2B 


u 




2C 
2D 
2E 
2F 


w 

X 




30 
31 
32 
33 


y 

z 




34 
35 
36 
37 


, 


© 


38 
39 
3A 
3B 




BY 
LF 


3C 
3D 
3E 
3F 




EGB 
PRE 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 


- 


® 


44 
45 
46 
47 


k 
1 




48 
49 
4A 
4B 


m 
n 




4C 
4D 
4E 
4F 


o 
P 




50 
51 
52 
53 


q 

r 




54 
55 
56 
57 


$ 




58 
59 
5A 
5B 




RES 
NL 


5C 
5D 
5E 
5F 




BS 
IL 


60 
61 
62 
63 


& 

a 




64 
65 
66 
67 


b 
c 




68 
69 
6A 
6B 


d 
e 




6C 
6D 
6E 
6F 


f 

g 




70 
71 
72 
73 


h 




74 
75 
76 
77 




© 


78 
79 
7A 
7B 




HT 


7C 
7D 
7E 
7F 




LC 
DEL 



S/360 
Byte (hex) 


Graphic 


Control 


80 
81 
82 
83 


= 


SP 
EGA 


84 
85 
86 
87 


< 




88 
89 
8A 
8B 


% 




8C 
80 
8E 
8F 


> 




90 
91 
92 
93 


( 




94 
95 
96 
97 


\ 




98 
99 
9A 
98 




RS 


9C 
9D 
9E 
9F 




UC 


AO 
Al 
A2 
A3 


? 




A4 
A5 
A6 
A7 


S 

T 




A8 
A9 
AA 
AB 


U 
V 




AC 
AD 
AE 
AF 


w 

X 




BO 
Bl 
B2 
83 


Y 

z 




84 
85 
86 
87 


1 


© 


88 
89 
BA 
8B 




BY 

LF 


BC 
BD 
BE 
BF 




EGB 
PRE 



S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 


J 


© 


C4 
C5 
C6 
C7 


K 

L 




C8 
C9 
CA 
CB 


M 
N 




CC 
CD 
CE 
CF 


G 
P 




DO 
D1 
D2 
D3 


Q 
R 




D4 
D5 
D6 
D7 


1 




D8 
D9 
DA 
DB 




RES 
NL 


DC 
DD 
DE 
DF 




BS 
IL 


EO 
El 
E2 
E3 


+ 
A 




E4 
E5 
E6 
E7 


B 
C 




E8 
E9 
EA 
EB 


D 
E 




EC 
ED 
EE 
EF 


F 
G 




FO 
F1 
F2 
F3 


H 
1 




F4 
F5 
F6 
F7 


— 1 


© 


F8 
F9 
FA 
FB 




HT 


FC 
FD 
FE 
FF 




LC 
DEL 



Figure 52. Line Code (EBCD) for IBM 2741 Communication Terminal 
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s/360 
Byte (hex) 


Graphic 


Gsntrol 


00 
01 
02 
03 


1 3 


SP 


04 
05 
06 
07 


2 
3 




08 
09 
OA 
OB 


5 

7 




OC 
OD 
OE 
OF 


6 
8 




10 
11 
12 
13 


4 





14 
15 
16 
17 


z 
9 


EOA 


18 
19 
lA 
IB 




PN 
RS 


IC 
ID 
IE 
IF 




Upshft 
EOT 


20 
21 
22 
23 


t 

X 




24 
25 
26 
27 


n 
u 




28 
29 
2A 
2B 


e 
d 




2C 
2D 
2E 
2F 


k 
c 




30 
31 
32 
33 


1 
h 




34 
35 
36 
37 


b 




38 
39 
3A 
3B 




BYP 
Index Attn 


3C 
3D 
3E 
3F 




EOB 
PRE 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 


! 
m 




44 
45 
46 
47 


V 




48 
49 
4A 
4B 


r 




4C 
4D 
4E 
4F 


a 




50 
51 
52 
53 


o 
s 




54 
55 
56 
57 


w 




58 
59 
5A 
5B 




RES 
LF-CR 


5C 
5D 
5E 
5F 




BS 
IL 


60 
61 
62 
63 


i 
g 




64 
65 
66 
67 


f 




68 
69 
6A 
6B 


p 




6C 
6D 
6E 
6F 


q 




70 
71 
72 
73 


/ 
y 




74 
75 
76 
77 


- 




78 
79 
7A 
7B 




Tab 


7C 
7D 
7E 
7F 




Dwnshft 



S/360 
Byte ^ex) 


Graphic 


Control 


80- 
81 
82 
83 


t c 


SP 


84 
85 
86 
87 


@ 
# 




88 
89 
8A 
8B 


% 
& 




8C 
8D 
8E 
8F 


* 




90 
91 
92 
93 


$ 
) 




94 
95 
96 
97 


z 

( 




98 
99 
9A 
9B 






9C 
9D 
9E 
9F 




Upshft 
EOT 


AO 
Al 
A2 
A3 


T 
X 




A4 
A5 
A6 
A7 


N 
U 




A8 
A9 
AA 
AB 


E 
D 




AC 
AD 
AE 
AF 


K 
C 




BO 
B1 
B2 
B3 


L 
H 




B4 
B5 
B6 
B7 


B 




B8 
B9 
BA 
BB 




Index Attn 


BC 
BD 
BE 
BF 







S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 




M 




C4 
C5 
C6 
C7 


V 




C8 
C9 
CA 
CB 


R 




CC 
CD 
CE 
CF 


1 
A 




DO 
Dl 
D2 
D3 



S 




D4 
D5 
D6 
D7 


W 




D8 
D9 
DA 
DB 




LF-CR 


DC 
DD 
DE 
DF 




BS 


EO 
El 
E2 
E3 


J 

G 




E4 
E5 
E6 
E7 


F 




E8 
E9 
EA 
EB 






EC 
ED 
EE 
EF 







FO 
Fl 
F2 
F3 


Y 




F4 
F5 
F6 
F7 






F8 
F9 
FA 
FB 




Tab 


FC 
FD 
FE 
FF 




Dwnshft 



i 



Figure 53. Line Code (Correspondence) for IBM 2741 Communication Terminal 
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5/360 


Graphic 


Control 


Byte (hex) 






00 






01 


T 




02 




CR 


03 


O 




04 




SP 


05 


H 




06 


N 




07 


M 




08 




LF 


09 


L 




OA 


R 




OB 


G 




oc 


, 




OD 


P 




OE 


C 




OF 


V 




10 


E 




11 


Z 




12 


D 




13 


B 




14 


S 




15 


Y 




16 


F 




17 


X 




18 


A 




19 


W 




lA 


J 




IB 




FIGS 


IC 


U 




ID 


Q 




IE 


K 




IF 




LTRS 


20 






21 


5 




22 




CR 


23 


9 




24 




SP 


25 


'a 


STOPc 


26 


/a 7/8c 




27 






28 




LF 


29 


\ 3/4, 




2A 


'^ 4 




2B 


& 




2C 


8 




2D 







2E 


^A V8c 




2F 


'A 3/8, 




30 


3 




31 


" 




32 


$ 




33 


?A ^8c 




34 




Belle 


35 


* 6 




36 


2a V4c 




37 


/ 




38 


« 




39 


2 




3A 




BellA 


3B 




FIGS 


3C 


7 




3D 


1 




3E 


<A ^/2c 




3F 




LTRS 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 






44 
45 
46 
47 






48 
49 
4A 
46 






4C 
4D 
4E 
4F 






50 
51 
52 
53 






54 
55 
56 
57 






58 
59 
5A 
5B 






5C 
5D 
5E 
5F 






60 
61 
62 
63 






64 
65 
66 
67 






68 
69 
6A 
6B 






6C 
6D 
6E 
6F 






70 
7) 
72 
73 






74 
75 
76 
77 






78 
79 
7A 
7B 






7C 
7D 
7E 
7F 







S/360 
Byte (hex) 


Graphic 


Control 


80 
81 
82 
83 






84 
85 
86 
87 






88 
89 
8A 
8B 






8C 
8D 
8E 
8F 






90 
91 
92 
93 






94 
95 
96 
97 






98 
99 
9A 
9B 






9C 
9p 
9E 
9F 






AO 
A1 
A2 
A3 






A4 
A5 
A6 
A7 






A8 
A9 
AA 
AB 






AC 
AD 
AE 
AF 






BO 
B1 
B2 
B3 






B4 
B5 
B6 
B7 






B8 
B9 
BA 
BB 






BC 
BD 
BE 
BF 







S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 






C4 
C5 
C6 
C7 






C8 
C9 
CA 
CB 






CC 
CD 
CE 
CF 






DO 
Dl 
D2 
D3 






D4 
D5 
D6 
D7 






D8 
D9 
DA 
DB 






DC 
DD 
DE 
DF 






EO 
€1 
E2 
E3 






E4 
65 
E6 
E7 






E8 
E9 
EA 
EB 






EC 
ED 
EE 

EF 






FO 
F1 
F2 
F3 






F4 
F5 
F6 
F7 






F8 
F9 
FA 
FB 






FC 
FD 
fE 
FF 







Figure 54. Line Code for AT &T 83B3 and WU 1 1 5 A Terminals 
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s/360 
Byte (hex) 


Graphic 


G>ntrol 


00 
01 
02 
03 


@ 


NUL 
NUL 


04 
05 
06 
07 




SP 


08 
09 
OA 
OB 


P 
P 


DLE 


OC 
OD 
OE 
OF 








10 
11 
12 
13 


H 
H 


BS 


14 
15 
16 
17 


( 
( 

h 




18 
19 
lA 
IB 


X 


CAN 
CAN 


IC 
ID 
IE 
IF 


X 




20 
21 
22 
23 


D 
D 


EOT 


24 
25 
26 
27 


$ 

$ 

d' 




28 
29 
2A 
2B 


T 


Tp Aux Off 
Tp Aux Off 


2C 
2D 
2E 
2F 


4 

t 
t 




30 
31 
32 
33 


L 


FF 
FF 


34 
35 
36 
37 


!' 




38 
39 
3A 
3B 




FS 


3C 
3D 
3E 
3F 


< 
< 

3 





S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 


B 
B 


STX 


44 
45 
46 
47 






48 
49 
4A 
4B 


R 


Tp Aux On 
Tp Aux On 


4C 
4D 
4E 
4F 


2 

r 1 
rl 




50 
51 
52 
53 


J 


LF 
LF 


54 
55 
56 
57 


!'; 




58 
59 
5A 
5B 


z 

z 


SUB 


5C 
5D 
5E 
5F 


z' 




60 
61 
62 
63 


F 


ACK 
ACK 


64 
65 
66 
67 


& 
f^ 




68 
69 
6A 
6B 


V 
V 


SYN 


6C 
6D 
6E 
6F 


6 
yl 




70 
71 
72 
73 


N 
N 


SO 


74 
75 
76 
77 


• 
• 




78 
79 
7k 
78 


t 


RS 
RS 


7C 
7D 
7E 
7F 


> 
—1 





S/360 
Byte (hex) 


Graphic 


Control 


80 
81 
82 
83 


A 
A 


SOH 


84 
85 
86 
87 


! 
! 




88 
89 
8A 
8B 


Q 


X-On 
X-On 


8C 
8D 
8E 
8F 


'i 




90 
91 
92 
93 


1 


HT 
HT 


94 
95 
96 
97 


) 

;1 
II 




98 
99 
9A 
9B 


Y 

Y 


EM 


9C 
9D 
9E 
9F 


9 
9 




AO 
Al 
A2 
A3 


E 


WRU 
WRU 


A4 
A5 
A6 
A7 


% 
el 
el 




A8 
A9 
AA 
AB 


U 
U 


NAK 


AC 
AD 
AE 
AF 


5 
5 

u' 




BO 
B1 
B2 
B3 


M 
M 


CR 


B4 
B5 
B6 
B7 


m 




B8 
B9 
BA 
BB 


3 


GS 
GS 


BC 
BD 
BE 
BF 


= 





S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 


c 


ETX 
ETX 


C4 
C5 
C6 
C7 


# 

c1 
cl 




C8 
C9 
CA 
CB 


S 

s 


EOT X-Off 


CC 
CD 
CE 
CF 


3 
3 

si 




DO 
Dl 
D2 
D3 


K 
K 


VT 


D4 
D5 
D6 
D7 


+ 
+ 




D8 
D9 
DA 
DB 


C 


ESC 
ESC 


DC 
DD 
DE 
DF 


' 




EO 
El 
E2 
E3 


G 
G 


Bell 


E4 
E5 
E6 
E7 


1 
1 91 




E8 
E9 
EA 
EB 


w 


ETB 
ETB 


EC 
ED 
EE 
EF 


7 
wl 




FO 
Fl 
F2 
F3 


O 


SI 
SI 


F4 
F5 
F6 
F7 


•: 




F8 
F9 
FA 
FB 


-- 


US 


FC 
FD 
FE 
FF 


? 
? 


Rubout 



Note 1 : Lower case letters are converted to upper case in the terminal. 



Note 2: Not all control characters are used by TWX but all are legitimate. 

Figure 55. Line Codes for AT&T TWX Terminals 



i 
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S/360 


Graphic 


Control 


Byte (hex) 






00 






01 


T 




02 




CR 


03 


O 




04 




SP 


05 


H 




06 


N 




07 


M 




08 




LF WRU 


09 


L 




OA 


R 




OB 


G 




OC 


1 




OD 


P 




OE 


C 




OF 


V 




10 


E 




11 


Z 




12 


D 




13 


B 




14 


s 




15 


Y 




16 


F 




17 


X 




18 


A 




19 


W 




lA 


J 




IB 




FIGS 


IC 


U 




ID 


Q 




IE 


K 




IF 




LTRS 


20 






21 


5 




22 




CR 


23 


9 




24 




SP 


25 






26 


^ 




27 






28 




LF 


29 


) 




2A 


4 




2B 






2C 


8 




2D 







2E 






2F 


= 




30 


3 




31 


+ 




32 




WRU 


33 


? 




34 


. 




35 


6 




36 






37 


/ 




38 


_ 




39 


2 




3A 




Bell 


3B 




FIGS 


3C 


7 




3D 


1 




3E 


{ 




3F 




LTRS 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 






44 
45 
46 
47 






48 
49 
4A 
4B 






4C 
4D 
4E 
4F 






50 
51 
52 
53 






54 
55 
56 
57 






58 
59 
5A 
5B 






5C 
5D 
5E 
5F 






60 
61 
62 
63 






64 
65 
66 
67 






68 
69 
6A 
6B 






6C 
6D 
6E 
6F 






70 
71 
72 
73 






74 
75 
76 
77 






78 
79 
7k 
7B 






7C 
7D 
7E 
7F 







S/360 
Byte (hex) 


Graphic 


Control 


80 
81 
82 
83 






84 
85 
86 
87 






88 
89 
8A 
8B 






8C 
8D 
8E 
8F 






90 
91 
92 
93 






94 
95 
96 
97 






98 
99 
9A 
9B 






9C 
9D 
9E 
9F 






AO 
Al 
A2 
A3 






A4 
A5 
A6 
A7 






A8 
A9 
AA 
AB 






AC 
AD 
AE 
AF 






BO 
B1 
B2 
B3 






B4 
B5 
B6 
B7 






B8 
B9 
BA 
BB 






BC 
BD 
BE 
BF 







S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 






C4 
C5 
C6 
C7 






C8 
C9 
CA 
CB 






CC 
CD 
CE 
CF 






DO 
Dl 
D2 
D3 






D4 
D5 
D6 
D7 






D8 
D9 
DA 
DB 






DC 
DD 
DE 
DF 






EO 
El 
E2 
E3 






E4 
E5 
E6 
E7 






E8 
E9 
EA 
EB 






EC 
ED 
EE 
EF 






FO 
Fl 
F2 
F3 






F4 
F5 
F6 
F7 






F8 
F9 
FA 
FB 






FC 
FD 
FE 
FF 







Figure 56. Line Code for IBM World Trade Telegraph ITA2 
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s/360 


Graphic 


ConlTol 


Byte (hex) 






00 






01 


T 




02 




CR 


03 


O 




04 




SP 


05 


H 




06 


N 




07 


M 




08 




LF WRU 


09 


L 




OA 


R 




OB 


G 




OC 


i 




OD 


P 




OE 


C 




OF 


V 




10 


E 




n 


Z 




12 


D 




13 


B 




14 


S 




15 


Y 




16 


F 




17 


X 




18 


A 




19 


W 




lA 


J 




IB 




FIGS 


IC 


U 




ID 


Q 




IE 


K 




IF 




LTRS 


20 






21 






22 




CR 


23 






24 




SP 


25 


? 




26 


, 




27 


7 




28 




LF 


29 


) 




2A 


/ 




2B 







2C 




Bell 


2D 


9 




2E 


8 




2F 


= 




30 


_ 




31 






32 




WRU 


33 


6 




34 


' 




35 


5 




36 


4 




37 






38 


+ 




39 


3 




3A 


2 




3B 




FIGS 


3C 


1 




3D 






3E 


( 




3F 




LTRS 



S/360 
Byte (hex) 


Graphic 


Control 


40 
41 
42 
43 






44 
45 
46 
47 






48 
49 
4A 
4B 






4C 
4D 
4E 
4F 






50 
51 
52 
53 






54 
55 
56 
57 






58 
59 
5A 
5B 






5C 
5D 
5E 
5F 






60 
61 
62 
63 






64 
65 
66 
67 






68 
69 
6A 
6B 






6C 
6D 
6E 
6F 






70 
71 
72 
73 






74 
75 
76 
77 






78 
79 
7A 
7B 






7C 
7D 
7E 
7F 







S/360 
Byte (hex) 


Graphic 


Control 


80 
81 
82 
83 






84 
85 
86 
87 






88 
89 
8A 
8B 






8C 
8D 
8E 
8F 






90 
91 
92 
93 






94 
95 
96 
97 






98 
99 
9A 
9B 






9C 
9D 
9E 
9F 






AO 
Al 
A2 
A3 






A4 
A5 
A6 
A7 






A8 
A9 
AA 
AB 






AC 
AD 
AE 
AF 






BO 
Bl 
B2 
B3 






B4 
B5 
B6 
B7 






B8 
B9 
BA 
BB 






BC 
BD 
BE 
BF 







S/360 
Byte (hex) 


Graphic 


Control 


CO 
CI 
C2 
C3 






C4 
C5 
C6 
C7 






C8 
C9 
CA 
CB 






CC 
CD 
CE 
CF 






DO 
Dl 
D2 
D3 






D4 
D5 
D6 
D7 






D8 
D9 
DA 
DB 






DC 
DD 
DE 
DF 






EO 
El 
E2 
E3 






E4 
E5 
E6 
E7 






E8 
E9 
EA 
EB 






EC 
ED 
EE 
EF 






FO 
Fl 
F2 
F3 






F4 
F5 
F6 
F7 






F8 
F9 
FA 
FB 






FC 
FD 
FE 
FF 




DEL 



Figure 57. Line Code for IBM World Trade Telegraph ZSC3 
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Appendix E: Running QTAM Application Programs Under TCAM 

This section provides a brief summary of the changes needed to run a QTAM 
Message Processing Program using TCAM. For more details, see OS Conversion 
Guide from QTAM or BTAM to TC^^M , Order No. GC30-2026. 

Using an Unmodif ied. Existing Program 

If the QTAM processing program is written so that the only QTAM macros issued 
are DCB, OPEN, CLOSE, GET, and PUT, the program need not be reassembled. 
Substitute the QTAM DD statements related to each process (input) and destina- 
tion (output) DCB macro with corresponding TCAM DD statements. The format 
of the DD statement is 

//ddname DD QNAME=procname 

ddname is the symbolic name of the DD statement, and must be the same as the 
name specified in the DDNAME= operand of the process or destination DCB 
macro. 

procname is the name of the process entry in the terminal table to which this entry 
refers. This name is assigned by the TPROCESS macro creating the entry. The 
destination queue may be changed at execution time by specifying a different 
value for the QNAME= parameter. 

Reassembling a QTAM Processing Program 

If macros other than OPEN, CLOSE, GET, PUT, and DCB are included in the 
application program, the program must be reassembled. A QSTART macro must 
be added as the first instruction of the program, immediately after the START or 
CSECT statement. 

The QSTART macro distinguishes QTAM and TCAM application programs by 
indicating whether the QTAM program is to be assembled to run under QTAM or 
TCAM. QSTART is not coded in a TCAM appHcation program, unless the 
CKREQ macro is used in a TCAM statement. There are no operands, and no 
assembler instructions are generated. The QSTART macro has an optional name 
field. 

QTAM Macro Facilities 

If a QTAM program is reassembled with a QSTART macro included, only some 
macro facilities are available. Password protection, as provided in TCAM, is not 
available. The following chart summarizes the macro facihties. 

Macro Facility 

RETRIEVE Transfers a message segment already 

placed on a destination queue or a 
process queue to a user-provided 
work area. 

RELEASEM Activates a designated terminal for 

(h receipt of message traffic from the 

1/ cpu^ 
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CLOSEMC 



Initiates termination of the TCAM 
Message Control Program. Provides 
a flush closedown only. 



STARTLN 


Activates a designated line for 




operation. 


STOPLN 


Deactivates a designated line from 




operation. 


COPYP 


No-Op. 


COPYQ 


No-Op. 


COPYT 


No-Op. 


CHNGT 


No-op. 


CHNGP 


No-Op. 



i 
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Appendix F: Summary of Operator Commands Classified by Operation 



This appendix groups all commands according to the type of operation (for 
instance, DISPLAY, MODIFY, RELEASE) being performed. The following list 
groups commands according to the areas in the TCAM system that are affected by 
issuing operator commands. 

See Operator Control in the chapter Using TCAM Service Facilities for an 
explanation of operator command format and how to specify operator commands. 



Operation 



Operands 



Operator Command 
Name 



DISPLAY ( TP,ACT, \ grpname,rln 
D ) J address 

TP,ADDR,statname 

TP,INACT,\ grpname,rln 
*] address 

TP,INTER 

TP,LINE, \ grpname,rln 
J address 

TP,LIST, \ grpname,rln 

i address 

TP,OPTION,statname,opfldname 

TP,PRITERM 

TP,QUEUE,statname 

TP,SECTERM 

TP,TERM,statname 



ACTVATED 

RLNSTATN 
INACTVTD 

INTRCEPT 
LNSTATUS 

STATDISP 

OPTFIELD 

DPRIOPCL 

QSTATUS 

DSECOPCL 

STSTATUS 



HALT 
Z 



TP, JqUICk/ 

/flush j 



SYSCLOSE 



hold( 



TP=statname 



SUSPXMIT 



MODIFY 
F 



id,AUTOPOLL= 
id,AUTOPOLL= 



grpname 
address 

grpname 
address 



,rln) , 
,rln), 



OFF 
ON 



id,INTER V AL = POLL,statname ,data 

id,INTERVAL= SYSTEM 

id,INTERVAL=SYSTEM,data 

id,INTENSE= LINE, j grpname, rln 
1 address 
sense, count 

id,INTENSE=TERM,statname,sense, count 



'X- 



AUTOSTOP 

AUTOSTRT 

POLLDLAY 
INTERVAL 
SYSINTVL 
ERRECORD 

ERRECORD 
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Uperation Operand 



id,OPERATOR= i statname ) 
\ SYSCON / 

id,OPT=statname,opfldname,data 

id,TRACE= i grpname,rln | ,OFF 
\ address j 

id,TRACE= ( grpname,rln \ ,ON 
( address j 



^Operator Commandr/' 
Name 



CPRIOPCL 



DATOPFLD 
NOTRACE 

GOTRACE 



J RELEASE I TP=statname 



RESMXMIT 



(vary 

I V 



statname,ONTP,B 
statname,ONTP,E 
gpstatname,OFFTP 



•{b} 



gpstatname,ONTP,fe ) 

statname,OFFTP,B 

statname,OFFTP,E 

i (grpnamcrln) ) ,OFFTP,i C \ 
j(grpname,) > I I f 

' address J 

( (grpname,rln) | ,ONTP 

j(grpname,) 

' address 



ACTVBOTH 

ENTERING 

GENPOLOFF 

GENPOLON 

NOTRAFIC 

NOENTRNG 

STOPLINE 

STARTLINE 



{ 
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Appendix G: Device-Dependent Considerations 



Details presented in this section pertain to specific devices (except for the general 
information on binary synchronous (BSC) devices) supported by TCAM. Con- 
siderations are Usted for start-stop and BSC devices; the final section of this 
appendix comprises considerations for the IBM 50 Magnetic Data Inscriber 
(MDI). More general information about the subject matter contained here can be 
found in the appropriate chapters of this publication. 



Start-Stop Devices 



1030 Data Collection System 

• On the STARTMH macro instruction, the CONV= YES operand must be 
coded if 1030 stations are included on lines processed by this Message Handler, 
since these stations do not have the capability of entering an EOT line-control 
character after their messages. CONV=(opfield, switch) may be coded when 
the TERMINAL macro for the 1030 station initializes the option field to the 
specified setting. 

• When the ADDR= operand of the TERMINAL macro is coded for a 1030 
station, the two addressing characters must be immediately preceded by a 37 
(this is the hexadecimal equivalent of the "circle S" character for the 1030). 
Neither the 37 nor the addressing characters are framed; the addressing charac- 
ters must be the hexadecimal equivalent of the 1030 line code representation. 

Example: 

If the address of the 1030 is Bl, the ADDR= operand of the TERMINAL 
macro would be coded as follows: 

ADDR=376402 

where 64 and 02 are the hexadecimal equivalent of the Une-code representation 
of the characters B and 1, respectively. 

• TCAM will recognize a message of one data character from the IBM 1030. 

1050 Data Communication System 

• With regard to message translation, the character sets of the 1050 terminals 
contain lowercase as well as uppercase alphabetic characters. When messages 
from a 1050 are sent to stations or application programs that do not recognize 
codes for lowercase letters, the user should either enter only the uppercase form 
of alphabetic characters, or he should employ the 105F translation tables on the 
incoming side. These tables translate each incoming lowercase letter to the 
EBCDIC uppercase equivalent. These tables should also be specified if the 
source or destination of a message is entered at an IBM 1050 terminal in 
lowercase form; if the contents of the source or destination header field are not 
in uppercase form at the time an ORIGIN or FORWARD macro is executed, 
the header information is assumed to be invalid. 

• The line correction feature is required if automatic retry is desired when a 
transmission error occurs. 
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1060 Data Communication System 

• On the STARTMH macro instruction, the CONV=YES operand must be 
coded if 1060 stations are included on lines processed by this Message Handler, 
since these stations do not have the capability of entering an EOT line-control 
character after their messages. CONV=(opfield, switch) may be coded when 
the TERMINAL macro for the 1060 station initializes the option field to the 
specified setting. 

2260 Display Station (Remote) 

• The last character of the invitation sequence (on the INVLIST macro instruc- 
tion) for a remote 2260 must be X*40' (this is the hexadecimal representation 
of the Read MI character). 

• When specifying the sequence of addressing characters, for a remote 2260, on 
the TERMINAL macro instruction, the user must code one of the following 
control characters immediately after the addressing sequence: 

• X'AO' for a Write-DC operation; 

• X*BO' for a Write-at-Line-Address operation; 

• X*EO' for a Write-Erase operation. 

The three operations are described in the discussion of the SCREEN macro 
instruction. 

• The 2260 translation table converts outgoing lowercase alphabetic characters 
to uppercase so that the terminal receives only uppercase characters. 

• The MSGLIMIT macro instruction is recommended for use with this type of 
terminal. The outheader subgroup for 2260s should include a MSGLIMIT 
macro specifying a limit of one message in inquiry applications (to ensure that a 
response message is not erased before it can be read). 

• Equal priority is recommended. 

• The MSGFORM macro instruction and the LC=OUT operand of the 
STARTMH macro instruction should be used when sending to the 2260 from 
other devices. 

• When the CUTOFF macro is executed, a 2848 Read-Skip with a 2848 Break is 
issued to terminate the transmission. 

• General Poll (see device-dependent considerations for the IBM 3270 Informa- 
tion Display System). 2260 uses a single address. 

2260 Display Station (Local) 

In coding the INVLIST, TERMINAL, and Une group DCB macros for the 2260 
Local configuration, you may consider each 2848 Control Unit attached locally to 
be a line group, and each 2260 station attached to such a control unit as a Une in 
that group; that is, you may code one DD statement and one line group DCB 
macro per control unit and one INVLIST macro per terminal. In addition, each 
2260 Local must be represented by a TERMINAL macro. 

• Issue one INVLIST macro instruction for each IBM 2260 Local Display 
Station; this macro must contain a single entry for the station. All 2260 Locals 
attached to the same IBM 2848 Display Control Unit may be considered to be 
in the same line group, or each 2260 may be defined separately; the INVLIST 
macros for these stations must be specified in the INVLIST= operand of the 
line group DCB macro according to ascending relative Une number. (Relative 
line number for 2260 Local stations in the same line group is determined by the 
order in which their TERMINAL macros are arranged; see the description of 
the TERMINAL macro.) 



The INVLIST entry for a 2260 Local should consist of the name of the station, i 

a "4-", and a one-byte code of X*02' (Read DS MI) indicating the type of Read 
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operation to be performed when data is entered at the station. For further 
information about this Read command, see IBM System/ 360 Component 
Description: IBM 2260 Display Station, IBM 2848 Display Control, 
GA27-2700. 

• Refer to the description of the SCREEN macro for information concerning 
output screen-control management. 

Example: 

The following INVLIST macro is for a 2260 Local station named STAl. 

L0CALST1 INVLIST ORDER=(STA 1+02 ) 

The X'02' causes a Read DS MI operation to be performed by TCAM when data 
is entered at the terminal. 

• Issue one TERMINAL macro per 2260 Local.. All TERMINAL macros for 
2260s on the same 2848 Control Unit must be grouped together. Assign each 
terminal a relative line number according to the position of its TERMINAL 
macro in the group; that is, in the first TERMINAL macro in the group, enter 
RLN=1, in the second, RLN=2, etc. 

Example: 

The following TERMINAL macro is the first in a group of macros representing 
2260 Local terminals attached to a 2848 Control Unit: 

TERM1 TERMINAL QBY=L,RLN=1 , DCB=DCB2260L, TERM=2260L, 
QUEUES=MO 

• The ADDR= operand of the TERMINAL macro is not meaningful for the 
2260 Local. 

• One line group DCB macro instruction may be coded for each locally attached 
2848 Control Unit. The INVLIST= operand should be coded so that the order 
in which the INVLIST macros for the terminals attached to the control unit are 
named in the operand corresponds to the order in which the TERMINAL 
macros for the terminals attached to the control unit are arranged. 

• Specify CPRI=S. Send priority for 2260 Locals is the same as that for non- 
switched contention stations, described in the transmission priority section of 
the chapter Defining Terminal and Line Control Areas . If the user has 
keyed in part of a message he wishes to enter, but has not actually entered it at 
the time TCAM sends a message to his terminal, the message Jie is attempting 
to enter is erased from his screen and must be re-entered at a later time. 

Example: 

The following line group DCB is for an IBM 2848 Control Unit attached locally. 

DCB2260L DCB DSORG=TX,MACRF=( G,P ) , * 

CPRI=S,DDNAME=DD2260L, * 

INVLIST=( L0CALST1 , , , * 

L0CALST2 , , , L0CALST3 , , ) , * 

PCI=(N,N),BUFIN=1 ,BUF0UT=2, * 
BUFSIZE=400 , BUFMAX=2 

The following DD statement would be included in the job control cards for the 
execute steps, if the 2260s were assigned the addresses 150, 151, and 152: 

l^ //DD2260L DD UNIT=150 

f // DD UNIT=151 

// DD UNIT=152 
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Dynamic PCI buffering is not recommended for the 2260 Local, as the data rate 
for this configuration is higher than for most other terminals. 

• TCAM recognizes a one-character message entered by a 2260 local station 
(generally, a message must be at least two bytes long in order to be recognized 
by TCAM). 

• For remote operations, the change specified by the SCREEN macro does not 
take effect until the next message is sent to the terminal. If this condition is 
not desirable, do not use the SCREEN macro. Instead, make the following 
coding changes: 

1. In the TERMINAL macro, code ADDR=xxxxOOFF where xxxx equals the 
addressing sequence. OOFF tells TCAM that the first byte of data in the 
current transmission is the control character to be used. 

2. Before issuing a PUT or WRITE in the application program or while the 
message is in the destination queue, insert the desired control character (X*AO', 
X*BO', or X*EO') in the first data character position of the current message 
header. If any other character appears in this first position, TCAM will auto- 
matically default to WDC. The use of WLA (X'BO') conforms to the line 
number requirements discussed under the SCREEN macro. 

3. Before sending the message to the addressed terminal, the control character in 
the first data character position in the header buffer must be replaced with an 
STX character by using the MSGEDIT macro or user code in the outheader 
subgroup of the Message Handler for the terminal. 



2265 Display Station 



• The MSGLIMIT macro instruction should be used for this type of terminal; the 
outheader subgroup for 2265s should include a MSGLIMIT macro specifying a 
limit of one message in inquiry applications (to ensure that a response message 
is not erased before it can be read). 

• Specifying receive priority with a user-determined delay may also be helpful. 

2740 Communications Terminal 

• With regard to message translation, the character sets of the IBM 2740 termi- 
nals contain lowercase as well as uppercase alphabetic characters. When 
messages from an IBM 2740 are sent to stations or appUcation programs that 
do not recognize codes for lowercase letters, the user should either enter only 
the uppercase form of alphabetic characters, or he should employ the 274F 
translation tables on the incoming side. These tables translate each incoming 
lowercase letter to the EBCDIC uppercase equivalent. These tables should also 
be specified if the source or destination of a message is entered at a 2740 
terminal in lowercase form. If the contents of the source or destination header 
field are not in uppercase form at the time an ORIGIN or FORWARD macro is 
executed,the header information is assumed to be invalid. 

2740 Terminals with Station Control, or Station Control and Checking 

• On the INVLIST macro instruction, the invitation sequence for this type of 
terminal consists of a single polling character, followed by a space character 
(X'Or in line code). 

• When a TERMINAL macro is coded for a 2740 with these features, the 
addressing sequence consists of a single polling character. Immediately preced- 
ing this character, X*37' should be coded; immediately following the character, 
X'Or should be coded. 
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2740 Terminals with Transmit Control, or Transmit Control and Checking 

• When coding an INVLIST macro for a 2740 with these features, the following 
invitation sequence must always be specified: X*230r (X and framing quotes 
are not coded). 

• On the TERMINAL macro, no addressing sequence should be specified for a 
2740 with these features. 



2740 Basic Terminals 



2740 Basic Dial 



On the TERMINAL macro, no addressing characters should be coded for any 
of the four IBM 2740 Basic terminal configurations supported by TCAM. 
Send priority is the suggested, method for using 2740 Basic terminals. 
If equal priority is specified for a 2740 Basic terminal on a nonswitched Une, 
messages may be entered at the terminal whenever the line is idle. The invita- 
tion list for this line may consist of one dummy entry (see the description of the 
INVLIST macro). The terminal operator may ask the computer to send by 
pressing the BID key and then pressing the EOT key. The computer then sends 
all messages queued for the terminal. After all messages are sent, the computer 
is again ready to receive messages. Messages queued for the terminal will also 
be sent as soon as the terminal operator enters a number of consecutive mes- 
sages in the sequence: BID key — message — EOT, which is equal to the num- 
ber specified by a MSGLIMIT macro coded in the inheader subgroup of the 
Message Handler for this line (see the description of the MSGLIMIT macro). 



• TCAM uses a Prepare command on 2740 Basic terminals and there is no 
time-out constraint; consequently, an operator must enter BID EOT to indicate 
to TCAM that he has no message to enter. 

2740 Terminals on a switched line 

• For 2740s on a switched line, after the terminal operator has finished entering 
his messages, he should press the BID key and then press the EOT key to 
indicate that he has no more messages to enter; otherwise, TCAM does not 
break the line connection. A 2740 Basic terminal on a switched line has a 
Prepare command that does not time out. 

2740 Model 2 Communication Terminal 

• The 2740-2 is defined as buffered by the BFDELAY= operand on the 
TERMINAL macro. (For more details, see the discussion of transmission 
priorities for nonswitched polled stations that use TCAM's buffering feature in 
the chapter Defining Terminal and Line Control Areas ). 

• Send priority must be specified (see the description of the CPRI= operand of 
the line group DCB macro instruction). 

• Queuing must be by terminal (see the description of the QBY=T operand of 
the TERMINAL macro instruction). 

• Lock mode (obtained by the LOCK macro instruction) must not be used with 
this terminal because of the danger of tying up the line. 

• The user need not concern himself with the size of the buffer for the 2740 
Model 2 with Checking (except when using the MSGFORM macro to insert 
EOB characters after each block of data; the user must specify a block size that 
will fit within the 2740 Model 2 buffer). After each block of text (delimited by 
an EOB) sent to the terminal, TCAM sends an EOT and will delay sending the 
next block of text to the terminal until the delay specified by the BFDELAY= 
operand of the TERMINAL macro has been observed. The EOB character 
may be inserted by the processing program or by using the MSGFORM macro. 
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• The user should be aware that the 2701,-2, or -3 transmission control units 
insert upshift and downshift characters that take up space in the 2740 Model 2 
hardware buffer. A block size should be specified small enough to prevent an f 
overrun condition in the 2740 Model 2. 

2741 Communications Terminal 

• Can enter messages directed to other stations, and can receive messages 
entered by itself. 

• Cannot receive messages from other stations unless the accepting 2741 is 
connected to a control unit equipped with the Transmit Interrupt (Reverse 
Break) feature. 

• Can receive messages directed to it from an application program, but only if 
such messages are responses to inquiries from the terminal, and message lock or 
extended lock mode is specified by the LOCK macro (these restrictions do not 
apply to terminals attached to control units equipped with the Transmit Inter- 
rupt (Reverse Break) feature). 

• Messages directed to the 2741 terminal must not contain an EOT line-control 
character. 

• Send priority must be specified by the CPRI= operand of the hne group DCB 
macro. 

• DIALNO=NONE must be specified in the TERMINAL macro for switched 
2741 stations. 

• For stations that do not perform parity and block checking (for example, IBM 
2740 Basic, IBM 2741, WTTC, TWX), you may wish to test for loss of incom- 
ing messages by coding a MSGGEN macro in your inmessage subgroup. 
MSGGEN should test bit 25 (error during text transfer) of the message error 
record and send a message to the source indicating that the latest message 

entered has been lost and should be re-entered, if bit 25 is on. 1 

• For 2741s on a switched line, after the terminal operator has finished entering "1 
all his messages, he should press the carrier-return key to indicate that he has 

no more messages to enter; otherwise, TCAM does not break the line connec- 
tion. 

• EOT must be stripped from outgoing messages. 

• If the keyboard locks while the terminal user is entering data, the user must 
reenter the complete message when the keyboard unlocks. 

• When error recovery procedures clear a unit exception condition (that occurred 
while a station was accepting messages), the first message after the wait excep- 
tion may be preceded by a circle D control character that is printed at the 
accepting station. 

2760 Optical Image Unit 

• For the user to perform conversational operations only, he must code the 
LOCK macro and the CONV=YES operand on the STARTMH macro. 

• The EOA sequence (X*160 is not written by TCAM; this character must be 
provided by the user or by the MSGFORM macro and must appear in the first 
position of each buffer. 

• The user program also must provide the PRE o sequence (X'3E4C') that 
directs messages sent from the CPU to the 2760. If provided in an application 
program,X*2796' is specified, and the message is sent through an MH contain- 
ing a CODE macro instruction. The folded translation table should not be used 
or X*2796' will be translated to X*27D6'. 

• TERM =27 60 should be coded for the TERMINAL macro to permit operation 
with both the 2760 and 2740. If TERM=274F, the 2760 cannot be successful- 
ly used. 
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3735 Programmable Buffered Terminal 

• The 3735 cannot be used as a primary or secondary operator control terminal. 

• The CLOCK= operand should be specified on the TERMINAL macro for a 
switched 3735. DIALNO=chars (also on TERMINAL) is necessary also. 

• Text transmissions to the 3735 must be in blocks of 476 characters or less. 

• The 3735 transmits data to the CPU in blocks of 476 characters; the last block 
of a transmitted message may contain less than 476 characters. 

• Send priority should be specified for the switched 3735. For more information, 
see Transmission Priority for Switched Stations in the chapter Defining 
Terminal and Line Control Areas. 

• The LOCK macro should be used for the switched 3735. 

7770 Audio Response Unit (ARU) 

• Issue one INVLIST macro for each TCAM audio line; that is, a line connected 
to an IBM 7770 Audio Response Unit, Model 3. This macro instruction assigns 
an invitation message to the line; the message is sent whenever a telephone or 
audio terminal calls in on the line. The operand of an INVLIST macro for an 
audio line has a single entry that consists of the name of the TERMINAL 
macro for the line over which the invitaition message is to be sent, the 
active/inactive entry indicator, and an invitational message which that is 
specified as CPU ID. 

The vocabulary of the ARU resides on an analog drum; a track on the drum can 
contain one word of the ARU's vocabulary Ust. To specify his invitation 
message, the user codes a series of pairs of hexadecimal digits in the CPU ID 
entry; each pair represents the address of a track containing one word of the 
message.For example, in the entry 

CPUID=INVMSG 

a message consisting of three words is specified by the constant INVMSG. 
These words are located on tracks 09, 01, and IB (hexadecimal notation) of the 
vocabulary drum. 

INVMSG DC X ' 03 * LENGTH OF INVITATIONAL MESSAGE 
X ' 090 11 B ' INVITATIONAL MESSAGE 

• The name of the INVLIST macro for an audio Une should be specified in the 
INVLIST = operand of the DCB macro for the Une group containing the line. 

Example: 

The following INVLIST macro instruction creates the invitation list for an 
audio line. 

LIST1 INVLIST ORDER=( BOS+ ) , CPUID=INVMSG 

BOS is the name of the TERMINAL macro instruction specifying 
UTERM=YES for this line. The + indicates that messages may be received on 
this line. 

• A TCAM audio line, that is, a line connected to an IBM 7770 Audio Response 
Unit, Model 3, requires a TERMINAL macro instruction coded with the 

h UTERM=YES operand. 

^ • The LOCK macro instruction is required for audio terminals. 
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World Trade Telegraph (WTTA) Terminals 

• For WTTA terminals, two message translation codes can be specified. These 
are International Telegraph Alphabet number 2 (ITA2) and Figure Protected 
Code (ZSC3). 

• If equal transmission priority is specified for a WTTA terminal on a non- 
switched contention line, messages may be entered at the terminal whenever 
the Hne is idle. Messages queued for the terminal will be sent only if a 
MSGLIMIT macro instruction is coded in the inheader subgroup of the Mes- 
sage Handler for this line, and then only when the number of messages entered 
by the terminal is equal to the number specified in the MSGLIMIT macro. 
Send priority is recommended. 

. The ADDR= operand of the TERMINAL macro must specify the WRU 
character rather than addressing characters. 

• When a message is entered from a World Trade Teletype terminal, one or more 
MSGGEN macros can be coded on a selective basis to inform the source 
terminal of receipt of the message, a transmission error, the need to re-enter the 
message, etc. 

• Since TCAM does not compare ID characters on a leased line, the ID character 
does not need to be specified in the INVLIST macro. 

Teletypewriter Exchange (TWX) Stations (AT&T 33/35 Dial) 

• All entries in an invitation list must have the same number of invitation charac- 
ters. If TWX stations on the same switched line are assigned ID sequences that 
differ in length, ID sequences shorter than the longest ID sequence specified in 
an INVLIST entry should be padded to the right with EBCDIC blanks to bring 
them up to the length of the longest sequence. The maximum-length, TWX ID 
sequence supported by TCAM is 23 bytes (including framing control charac- 
ters). It is recommended that each terminal ID sequence included as part of an 
invitation Ust entry be preceded and followed by certain control characters. 
These characters, and the hexadecimal representations of their line-code bit 
patterns (shown in non-parity TWX transmission code) are: 

a) characters 

CR LF idchars CR LF XON 

b) hexadecimal representation 

B151idcharsB15189 

An entry for a TWX terminal named RAL that is assigned the ID sequence 
IBM 35ASR #1 might be coded: 

RAL+B1519343B30fCDAD83CB4B05C58DB15189 

(If a TERMINAL macro coded UTERM=YES were issued for the line, the 
name of the TERMINAL macro would be coded in place of RAL.) For lines to 
TWX terminals, it is recommended that the computer ID sequence also be 
preceded and followed by certain control characters. These characters, and the 
hexadecimal representations of their line-code bit patterns, are: 

a) characters 

Null CR LF Rubout idchars CR LF XON 

b) hexadecimal representation 
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1 B 1 5 1 FFidchar SB 15189 

If the ID sequence were RALEIGH, the operand for the computer ID might be 
coded: 

CPUID=CPUNAME 

Somewhere within the same area of the MCP the following field would be 
defined: 

CPUNAME DC X ' OE ' 

DC X'01B151FF4B8333A393E313B15189' 

A table for translating TWX line code to hexadecimal representation is given in 
Appendix D. 

Example: 

The following INVLIST macro creates the invitation Ust for a switched line having 
three TWX terminals (named SCTN, PITT, and PHIL) assigned to it. Each of 
these terminals is assigned a unique ID sequence, consisting of its name. The 
computer is assigned the ID sequence PENN. It is assumed that the TWX termi- 
nals are non-parity machines. 

LIST1 INVLIST {SCTN+B151CBC32B73B15189, * 

PITT+B 1 5 1 0B932B2BB 15189, * 

PHIL+B151B131933B15189), * 
CPUID=TWXADDR 

Here, CBC32B73, 0B932B2B, and 0BI31933 are the TWX, non-parity, 
transmission-code representations of the ID sequences SCTN, PITT, and PHIL, 
respectively, in hexadecimal notation. Bl, 51, and 89 are the non-parity hexade- 
cimal representations of the TWX CR, LP, and XON line-control characters, 
respectively. Somewhere in the MCP the following field is defined: 

TWXADDR DC X'OB' 

DC X'01B151FF0BA37373B15189* 

In this instance, OB is the hexadecimal length of the rest of the field. OBA37373 is 
the non-parity, TWX, transmission-code representation of the ID sequence 
PENN, in hexadecimal notation. 01, Bl, 51, FF, and 89 are the non-parity, 
hexadecimal representations of the TWX Null, CE, LF, Rubout, and XON 
line-control characters, respectively. 

• Transmission priority for TWX stations: the computer invites the station to 
enter a message by sending the computer ID sequence to the station. The 
computer ID sequence is sent after each message is entered by the station, to 
invite the station to enter another message. When the station has no more 
messages to enter, the station operator should so inform the computer by 
pressing the XOFF key after receiving the computer ID sequence. 

• Two types of TWX terminals may be used with TCAM. The first of these 
enters and accepts parity data. For this type of TWX station, the TTYB 
translation table is provided. The second type of TWX station enters and 
accepts only non-parity data; that is, the parity bit must be one in all charac- 
ters. The TTYC translation table is provided for translating data received and 
sent to TWX terminals of this type. The user may wish to receive messages 
from or send messages to both types of TWX terminals over lines in the same 
line group, in which case he may issue two CODE macros in his incoming or 

P outgoing group and route each message to one or the other, as described in the 

section Variable Processing within a Message Handler. 
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• The user should end all TWX messages with the XOFF control character 
instead of with the EOT Une-control character. If EOT is used, the line is 
disconnected and a console error message is posted. 

• When the CUTOFF macro is executed a Write Break is issued to terminate the 
transmission. 

ATJkT 83 M3 Selective Calling Station 

• When specifying the sequence of addressing characters on the TERMINAL 
macro instruction for an AT & T 83B3 terminal, the user must code a LTRS 
(letters-shift) control character immediately after the two addressing charac- 
ters. The LTRS character is specified by coding X* IF'. The X and framing 
quotes are not coded. 

Binary Synchrmious Communication (BSC) Terminals 

In this section, information that is applicable to BSC devices in general will be 
presented first; following this general information will be sections deaUng with 
each BSC station supported by TCAM. 

TCAM Send and Receive Operations on a BSC Line 

This section presents TCAM's responses to various line-control characters entered 
by a station during an attempt on the part of TCAM to read messages entered by 
that station or to send messages to it, and describes conditions that TCAM 
interprets as errors during invitation, selection, and transmission. This informa- 
tion will be of interest to those who are programming a computer to serve as a 
remote station in a TCAM system, to the user whose application demands a 
knowledge of TCAM's line-control scheme, and to those interested in the various 
conditions that prompt TCAM to set bits in the message error record having to do 
with errors encountered while TCAM is reading or writing text on a BSC Une. 
For general information on BSC Une control, see the pubUcation General 
Information — Binary Synchronous Communications (GA27-3004). For detailed 
information on TCAM's channel programs and error-recovery procedures, see the 
TCAM PLM. 

In the following two sections, the statement is made in many places that TCAM's 
response to a particular error is to terminate its attempt to send or receive the 
current message. In this case, TCAM attempts to send or to receive the next 
eligible message. If no provision is made in the outmessage subgroup of an MH to 
test whatever error bits were set and to take appropriate action following an error, 
the message is treated by TCAM as if it had been successfully transmitted; no 
further attempt is made to send it. On the receiving side, if any data in the 
message in error is received, the portion of the message that was received is sent 
through the incoming group of the appropriate MH and is placed on the destina- 
tion queue for the destination (if the destination is known). 



SeB#ig Operations 



• If TCAM sends out an ENQ or an addressing sequence and receives a response 
other than ACK, WACK, or (on a multipoint line only) RVI, TCAM attempts 
six more times to elicit a satisfactory response; if none is received, TCAM sets 
bit 24 (selection error) in the message error record and terminates its attempt 
to send the current message. 

• If TCAM sends out an ENQ or an addressing sequence and receives an EOT in 
response, TCAM immediately sets bit 24 (selection error) in the message error 
record and terminates its attempt to send the current message. i 

For all point to point stations (including switched stations): 
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• If TCAM receives a WACK in response to an ENQ (indicating that the 
station's hardware buffer is busy), TCAM responds by writing another ENQ; 
this exchange is repeated until TCAM receives a response other than WACK. 
(A WACK in response to an ENQ can be received from an IBM 2770 station 
and from CPUs used as stations). 

• If TCAM receives a NAK in response to an ENQ, TCAM sets bit 24 (selection 
error) in the message error record and sends an EOT to the station, thereby 
terminating its attempt to send the current message. 

For point-to-point, nonswitched, contention stations 

• If TCAM receives an ENQ in response to an ENQ (indicating a contention 
situation), TCAM will yield if the MASTER=NO default is taken on the 
INVLIST macro for that Hne. In this case, TCAM automatically delays the 
current attempt to send, giving the station an opportunity to enter data; TCAM 
attempts to send the message later. If MASTER= YES is specified, TCAM 
attempts six more times to elicit a satisfactory response; if an ENQ is received 
each time, TCAM sets bit 24 (selection error) in the message error record and 
terminates its attempt to send the current message. 

For multipoint stations: 

• If TCAM receives a NAK in response to an addressing sequence, TCAM sets 
bit 24 (selection error) in the message error record and terminates its attempt 
to send the current message. 

• If TCAM receives an RVI in response to an addressing sequence and TCAM's 
buffered terminal support is specified (by the BFDELAY= operand of the 
TERMINAL macros for stations on the line), TCAM re-addresses the station 
at a later time, if the addressing characters were for the first segment in the 
message; if they were for a segment other than the first, TCAM sets bit 25 
(error during text transfer) and bit 7 (cutoff /RVI error) in the message error 
record and terminates its attempt to send the current message. If RVI is 
received in response to addressing characters for a station that is not using 
TCAM's buffered terminal support, TCAM re-sends the addressing sequence 
at a later time. 

For all BSC stations: 

• If TCAM receives, as a response to a block of text, a character other than 
ACK, NAK, WACK, RVI, or EOT, or receives no response at all, TCAM 
sends the station an ENQ six times; if none of the six ENQs elicit a satisfactory 
response, TCAM sets bit 25 (error during text transfer) in the message error 
record and sends an EOT to the station, thereby terminating its attempt to send 
the current message. 

• If TCAM receives an EOT in response to text, TCAM immediately sets bit 14 
(BSC abort) and bit 25 (error during text transfer) in the message error record 
and terminates its attempt to send the current message. 

• If TCAM receives a NAK in response to text, TCAM re-sends the block of text 
up to six times; if no satisfactory response is elicited, after six retries TCAM 
sets bit 25 (error during text transfer) in the message error record and sends the 
station an EOT, thereby terminating its attempt to send the current message. 

• If TCAM receives an RVI in response to text, TCAM considers this to be a 
normal response and continues sending. If an RVI is received as the response 
to two successive blocks of text, TCAM sends an ENQ in response to the 
second RVI. If another RVI is received in response to the ENQ, TCAM sends 
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Receiving Operations 



another ENQ; after six ENQ/RVI exchanges, TCAM sends the station an EOT 
and terminates its attempt to send the current message. 
• If TCAM receives a WACK in response to text sent to a BSC station using 
TCAM's buffered terminal support (indicating that the terminal's buffer space 
is exhausted), TCAM sends the station an EOT and sends the next block of 
text after the interval specified by the BFDELAY= operand of the 
TERMINAL macro has been observed. If WACK is received in response to a 
block of text sent to a station not using TCAM's buffered terminal support, 
TCAM sends an ENQ; if another WACK is received, the cycle is repeated until 
a different response is received by TCAM. 



• Terminals defined as buffered (by the BFDELAY= operand of the 
TERMINAL macro) can interleave input as well as output operations. TCAM 
considers a message to be a block of text ending with ETX followed by an 
EOT. This definition would be advantageous with a large, batch input message 
from the 2770 operating in inquiry mode. Two blocks of data will be read and 
the Une will be free for an output operation to another station or to service the 
next invitation list entry. TCAM considers the remaining data received to be a 
continuation of the same message until the ETX block is received followed by 
the EOT. In receiving subsequent data blocks from the 2770, the number of 
reserve characters in the first buffer is the number specified in the DCB for the 
first incoming segment plus the difference between header prefix size and text 
prefix size. TCAM will not send to any component on this station until the 
message being received has ended. Note that input from any component on 
this station that responds to polling will be accepted by TCAM as a continua- 
tion of the same message. Also, if a permanent error is encountered while 
attempting to poll any component on this station, data already read will be 
considered as a complete message that ended in an error. 

• Each block of incoming data must begin with a vaUd start character (SOH, 
STX, DLE/STX) and end with a valid end character (ETB, ETX, EOT). (In 
order t9 be valid, the EOT character must be transmitted by itself, as a separate 
block.) When this requirement is not met, TCAM assumes that an error has 
occurred and requests retransmission of the block. If the error has not been 
corrected after six retries, TCAM sets bit 21 (format error) and bit 25 (error 
during text transfer) in the message error record, and sends the station an EOT 
character. 

• Each incoming block of a message is required to be in the same transmission 
mode (transparent or nontransparent) as the other blocks of the message. If all 
blocks of the same message are not in the same transmission mode, TCAM sets 
bit 21 (format error) and bit 25 (error during text transfer) in the message error 
record. 

• When TCAM receives an ENQ character while attempting to read, TCAM 
sends back the previous acknowledgment character (ACKO or ACKl). 

• When TCAM receives a TTD (temporary text delay, STX-ENQ) sequence, 
TCAM responds with a NAK; this is not considered to be an error condition. 
When TCAM receives a TTD and the next block read in is an EOT (indicates a 
possible station malfunction resulting in a truncated message for a 2770 or 
2780 station), TCAM sets bit 14 (BSC abort) and bit 25 (error during text 
transfer) in the message error record. 

• When TCAM receives a station ID sequence on a switched BSC line, TCAM 
compares invitation lists for a matching ID sequence, beginning with the 
invitation list for the line over which the ID sequence was received and working 
upward through all Unes in the Une group having higher relative Une numbers 
than the line over which the ID sequence was received. 
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Other BSC Considerations 



If no match is found for a station ID sequence read in over a switched line, 
TCAM attempts to read in the ID sequence and find a match for it six more 
times. If these attempts are unsuccessful, TCAM sets bit 17 (invalid station ID) 
in the message error record, and terminates its attempt to send or receive the 
message. In addition, TCAM breaks the line connection with the station. 
If TCAM dials a BSC station on a switched line and receives an invalid ID 
sequence, TCAM re-sends the computer's ID-ENQ sequence six times; if no 
vaUd ID sequence is received from the station after six retries, TCAM sets bit 
17 (invalid station ID) in the message error record and breaks the telephone 
connection, thereby terminating its attempt to send the message eligible to be 
sent first to the station. 

TCAM provides Reverse Interrupt (RVI) support for BSC terminals. Informa- 
tion about implementation of this support is provided in the description of the 
LOGICAL= operand of the STARTMH macro. 



EOB checking must be specified by the STARTMH macro if the Message 
Handler is to operate on messages whose origin or destination is a BSC station 
(for directions on specifying EOB checking, see the description of STARTMH). 
On the INVLIST macro instruction, all entries in an invitation list must have 
the same number of invitation characters. This requirement presents a problem 
with respect to BSC stations on a multipoint line. BSC stations are compatible; 
that is, more than one type of BSC station may be included on the same line. 
Since different types of polled BSC stations require different numbers of 
polling characters (for example, a polled IBM 1 130 requires one polling charac- 
ter, while a polled IBM 2780 requires two), some polling sequences in an 
invitation list for a Une connecting different kinds of BSC terminals may have 
to be padded to bring them up to the length of the longest sequence. Synchro- 
nous idle characters are used to bring each sequence of poUing characters 
specified in an INVLIST entry for a polled BSC station up to the length of the 
longest sequence specified in any entry for that INVLIST macro. These 
characters are inserted to the left of the poUing characters. The synchronous 
idle characters used depend upon the transmission code for the station; appro- 
priate characters are: 

. for EBCDIC, X*32'; 

• for ASCII, X*16'; 

. for 6-bit Transcode, X*3A'. 

The X and the framing quotes are not coded. 

When creating an INVLIST entry for a polled BSC station, code the ENQ 
line-control character after each sequence of hardware polling characters; 
appropriate characters are: 

. for EBCDIC, X*2D'; 
. for ASCII, X'05'; 

• for 6-bit Transcode, X'2D'. 

The X and the framing quotes are not coded. For example, the entry for a 
polled IBM 2780 terminal named NYC that uses EBCDIC transmission code 
might be coded 

NYC+C1F62D 
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where C1F6 is the EBCDIC representation of the polling characters A6 in 
hexadecimal notation, and 2D is the EBCDIC representation of the ENQ 
line-control character in hexadecimal notation. 

• The EOT= operand of the INVLIST macro must be coded for BSC stations on 
a multipoint line. 

• TCAM supports four BSC ID schemes; the user can specify a CPU ID and no 
station ID, a station ID and no CPU ID, both a station ID and a CPU ID, or 
neither a station ID nor a CPU ID. 

• When BSC stations are assigned ID sequences, the unit size (as specified in the 
KEYLEN= operand of the INTRO macro) must be at least as long as the sum 
of the longest ID sequence that can be entered by a station plus one byte; 
otherwise, errors may occur. 

• If a unique ID is assigned to each BSC station on a switched line, no ORIGIN 
macro is needed to identify these stations. 

• The length of a CPU or station ID sequence must not be longer than 15 charac- 
ters. 

• If no ID exchange is desired for BSC stations on a switched line, the invitation 
list for that line should consist of a single entry containing the name of a single 
station on that line followed by a +. 

Example: TERMA+ 

• If a one-character station ID sequence is being used, the EBCDIC pad charac- 
ter (X*DF') should not be assigned as an ID. 

• If BSC stations on the same switched Une are assigned ID sequences that differ 
in length, ID sequences shorter than the longest ID sequence specified in an 
INVLIST entry should be padded to the right with EBCDIC blanks to bring 
them up to the length of the longest sequence. The maximum length BSC ID 
sequence is 15 bytes. 

• The sequence of addressing characters for a BSC station must be followed by 
the ENQ line-control character. Appropriate characters are: 

• for EBCDIC, X*2D'; 
. for ASCII, X'05'; 

• for 6-bit Transcode, X'2D' 

The X and framing quotes are not coded. 

• A switched line to BSC stations that are all assigned unique ID sequences does 
not require a TERMINAL macro instruction coded UTERM=YES. For such a 
line, the user should enter each station's name and ID sequence and the CPU 
ID sequence in the appropriate operands of the INVLIST macro instruction for 
the line. 

• If equal priority is specified for BSC point-to-point stations on a nonswitched 
contention hne, messages may be entered at the terminal whenever the line is 
idle.Messages queued for the terminal will be sent only if a MSGLIMIT macro 
instruction is coded in the inheader subgroup of the Message Handler for this 
line, and then only when the number of messages entered by the terminal is 
equal to the number specified in the MSGLIMIT macro instruction. 

• Send priority for switched stations: When a BSC station calls the computer, 
TCAM allows the station to enter a message. TCAM then sends all messages 
queued for the station before allowing the receipt of another message from the 
station. When the computer calls a BSC station at the expiration of the time 
specified on either the CLOCK= or the CINTVL= operand of the 
TERMINAL macro, TCAM allows the station to enter a message and then 
sends all messages queued for the station. With this priority scheme, TCAM 
transmits an EOT when the message queue is empty or after unsuccessful 
attempts to recover from line errors. The line is turned around when TCAM 
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transmits or receives an EOT. TCAM also transmits an EOT after a MSGGEN 
macro executes, resulting in a line turnaround. 

• Equal priority for switched stations: When a BSC station calls the computer, 
the computer allows the station to enter one message after the connection is 
estabUshed.The BSC station enters a message if it has one. The computer then 
sends the BSC station one message, if any is queued for the station, and if the 
calling station has identified itself by means of an ID sequence or an origin field 
(verified by an ORIGIN macro) in the message header. Messages are sent by 
the computer according to the priority scheme outlined in Message Priority 
and Queuing . The computer alternates between sending the BSC station a 
single message and pausing to permit the station to enter a single message until 
the message queue for the station is exhausted. If no input message is entered 
immediately, the computer pauses for nine seconds before sending the station 
the next message on its destination queue. (A computer serving as a remote 
station can avoid the nine-second delay by entering an EOT when it has no 
message to enter.) When the last incoming message is received and no further 
messages appear on the destination queue for the station, the computer breaks 
the line connection, making the Une available for new calls. This scheme also 
applies when the computer calls the station, except that the computer sends the 
first message (if it has one for the station) in this case. If the computer has 
nothing to send the station, and nothing comes in from the station, the comput- 
er breaks the Une connection. 

If a BSC station calls the computer and does not identify itself (that is, does not 
use ID verification), the computer allows the station to enter messages and sends 
the station the messages queued for this line. If no messages are queued for the 
line entry, and if the station has not identified itself by the time it enters its last 
f message, the computer breaks the line connection after giving the station a chance 

to enter and after receiving no message from the station. 

IBM 2770 Data Communications System 

• If 2770s are on multipoint lines, it is recommended that the stations be defined 
as buffered (by the BFDELAY= operand on the TERMINAL macro). 
Enough delay time should be specified by BFDELAY= to allow the terminal to 
empty one of its two hardware buffers. (TCAM's buffered terminal support is 
designed to optimize line usage for the 2770.) 

• Only multipoint 2770 stations should be defined as buffered. 

• Send priority must be specified for buffered terminals (see the description of 
the CPRI= operand of the line group DCB macro instruction). 

• Queuing must be by terminal (see the description of the QBY= operand of the 
TERMINAL macro instruction). 

• If the CONV= operand of the STARTMH macro specifies conversational 
mode for an MH handling messages being sent to a 2770 station, and if the 
station is set up so that selection of an output device is required, a device- 
selection character (X'lT, '12', or *13', depending upon the output device 
selected) must be specified as the first character following the STX Une-control 
character in each message sent to the 2770 station. The user must see to it that 
this character appears in his outgoing message — TCAM does not support 
transparent mode for messages being sent to 2770 stations requiring selection 
of an output device. 

• When attempting to select a point-to-point 2770 or 2780 station, TCAM sends 
an ENQ character, the station responds with ACKO, and TCAM writes the 

I escape sequence for the desired station component. If an RVI is received from 
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the station instead of ACKO, TCAM sends an EOT to the station and attempts 
to send the message at a later time. 

• Lock mode (obtained by the LOCK macro) must not be used with this terminal 
if TCAM's buffered terminal support is specified for it (by the BFDELAY= 
operand of the TERMINAL macro). 

• Operator commands must end with b char EOT rather than with bEOT. 

IBM 2780 Data Transmission Terminal 

• On the STARTMH macro instruction, the CONV=YES operand should not be 
coded if any 2780s are included on lines handled by this Message Handler; if it 
is coded, the BSC line integrity is destroyed. 

• For a 2780 point-to-point, when the computer sends information to the punch 
or printer, an escape sequence must be specified in the TERMINAL macro 
(ADDR=escape sequence). 

• When attempting to select a point-to-point 2770 or 2780 station, TCAM sends 
an ENQ character, the station responds with ACKO, and TCAM writes the 
escape sequence for the desired station component. If an RVI is received from 
the station instead of ACKO, TCAM sends an EOT to the station and attempts 
to send the message at a later time. 

2790 Data Communications System 

• The LMD option of TCAM is required for lines with 2790s (2715 Transmission 
Control Unit) attached. See Handling Logical Messages in the section 
Designing the Message Handler. 

• The SETEOM macro must be coded 

SETEOM PROCESS=YES , REMOVE=NO , EOM=ETB 

. PCI=(X,X) or PCI=(N,N) must be specified. 

• BSC 1 , BSC2, or BSC3 must be used. 

• A set of macro instructions (not listed in this document) is available to enable 
the user to define the tables and transactions required for a particular configu- 
ration. These tables contain pointers and indexes, as well as parameters, that 
are meaningful to the microcoded routines within the 2715. The user must 
assemble all macros at the same time since the relationship among the tables is 
established by labels. 

The assembly output of the user macros is a set of tables, in object form, needed 
for the 2715 internal operation. The user must write a TCAM application pro- 
gram to load this table in the 2715. An alternate option is to use a loading proce- 
dure such as BTAM. Seethe IBM 2790 Data Communications System Com- 
ponent Description (GA27-3015) and the IBM System/360 OS DOS BTAM 
Planning for IBM 2790 Data Communications System Support (C30-1004). 

3270 Information Display System 

The eight categories for device-dependent considerations for the IBM 3270 
Information Display System are: 

1. Input data stream. 

2. Output data stream. 

3. SCREEN macro format for the 3270. 

4. Defining terminal tables and invitation Usts. 

5. Specific and general poUing. 
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6. Coding considerations. 

7. Error handling for the 3270. 

8. Dynamic Buffering for Local 3270. 

To understand how the 3270 is supported by TCAM the user must be familiar 
with the contents of ^n Introduction to the IBM 3270 Information Display 
System (GA27-2739) and the /i?M 3270 Information Display System Compo- 
nent Description (GA27-2749). 



Input Data Stream 



Input from a remote 3270 is the result of execution of a Read Modified command. 
When a 3270 successfully receives vaUd polling characters, its positive response is 
to transmit to the CPU all fields in which modified data tag bits have been set in 
the attribute bytes. Translation from line code may be performed in the Message 
Handler with the CODE macro. 



The remote input data format is: 



S C D A C 


C 


T U V I U 


U 


X C D R 


R 



TEXT 



E 
T 
X 



Where: 

STX is the start-of-text, line-control character. 

CU is the control unit, fixed-return address. 

DVC is the device, fixed-return address. 

AID is the attention identification byte. 

CUR is the cursor address. 

ETX is the end-of-text, line-control character. 

The local input data format is: 



A C C 
I U U 
D R R 



TEXT 



Output Data Stream 



Output to a 3270 may originate either in an application program or a Message 
Handler, or in both. For example, a message created in an appUcation program 
may be augmented or edited by the MSGEDIT or MSGFORM macros in the 
Message Handler. For remote output data streams the command operator must be 
the EBCDIC representation of a valid 3270 output command. The command 
must be prefaced by an escape character (ESC). For local output the ESC and 
CMD must not be present. The SCREEN macro may be used to alter output 
commands for both remote and local 3270 devices. For remote devices the 
SCREEN macro inserts commands into the data stream. Local channel programs 
corresponding to the data stream command may be generated by action of the 
SCREEN macro or the command may be specified in the macro. For information 
about SCREEN macro coding see the Designing the Message Handler section of 
this manual and the description of the SCREEN macro for 3270 in this appendix. 

Translation into line code may be performed in the Message Handler with the 
CODE macro. 
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The remote output data format is: 
TEXT 



S E C W 
T S M C 
XC D C 



E 
T 
X 



Where: 

CMD is the command operator. 

WCC is the write cdntrol character. 

The local output data stream appears as follows before processing by the 
SCREEN macro: 



W 

C TEXT 

C 

SCREEN Macro Format for the 3270 



Name 


Operation 


Operands 


[symbol] 


SCREEN 


( WDCH.conchars ,BLANK= (yES )] 
JWREJ "(no > 
' EAU ' ( char ) 

[,retrv=/yes \I 

\NO/ 



symbol 




Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to rules for assembler language symbols. 



Function: Specifies the type of write operation. 

Default: WDC for local output. Specification optional for remote output. 

Format: WDC, WRE, or EAU. 

Notes: The WDC (write display cursor) operation specifies that data will be 

written starting at the cursor position. The WRE (write erase) operation specifies 

that the entire screen will be erased before writing the output. The EAU (erase all 

unprotected) operation specifies: 

• on a formatted screen all unprotected fields will be erased; 

• on a non-formatted screen the entire screen will be erased. 

The EAU operation will not allow any data to be written out following the era- 
sure. However, for 3270 local devices only, the EAU command indirectly points 
to a buffer address and the information at this buffer address will be lost during 
the execution of the EAU command. Therefore, an expendable buffer should be 
used when the EAU operand is specified on the SCREEN macro. All the data in 
this expendable buffer will be lost (not sent to its destination). The WDC, WRE, 
and EAU operations are performed immediately on the buffer currently being 
processed. 
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conchars 



blank=(yes) 

Vchar ) 



retrv=(yes) 

iNOj 



Function: See the description of the SCREEN macro in the Message Handler 
section of this manual. 



Function: See the description of the SCREEN macro in the Message Handler 
section of this manual. 



Function: When RETRV=YES is coded the command byte is extracted from a remote 
data stream (located in the data portion of the buffer), converted to the local equivalent, 
and inserted in the local channel program. The remote data stream remains unchanged. 
Default: NO 

Format: RETRV=YES or RETRV=NO 

Notes: The RETRV= operand is designed for those users who wish to send 3270 remote 
data to a 3270 local device. There is, in the 3270 remote data stream, the command 
code WDC (write display cursor), WRE (write erase), or EAU (erase all unprotected). 
When RETRV=YES is coded on the SCREEN macro (for sending to a 3270 local device) 
the type of command in the remote data stream is used to transmit the message to the 
local 3270 device. The command code in the data stream must immediately follow the 
escape character, and both the escape character and the command code must be located 
in the first unit of the first header buffer at the time the SCREEN macro is executed. 

The RETRV= operand applies only to local 3270 devices. However, if it is specified for 
a remote 3270 device it will be ignored and not be flagged as an error as long as a valid 
operation code (WDC, WRE, or EAU) has been specified. If RETRV=YES and a valid 
operation (EAU, WRE, WDC) are specified, the operation will only be used when the 
command code cannot be found in the first unit of the first buffer containing the data 
stream. Otherwise the operation vvill be ignored. If both the operation code and the 
RETRV=YES operands are omitted the SCREEN routine will return code X'04' in 
register 15. See Message-Handler Macro Return Codes in Designing the Message Handler. 

Example: A user wishes to send message to a local 3270 display device. The RETRV= 
YES operand is coded in the SCREEN macro of the outgoing MH. Before each message 
is written out the screen is to be erased. 

The user's appHcation program constructs only remote command order streams in a 
buffer with the following format: 



PREFIX 


HDR 


X'02' 


X'27' 


X'F5' 


MESSAGE 



12 30 Data Stream 

Bytes Bytes 

The X'27' is the escape character followed immediately by the command code XT5' 
erase/write (WRC) for the 3270 remote display device. When the SCREEN macro is 
executed in the MH, the screen processor will find the X'F5' command code immediately 
following the escape character X'27', and TCAM will construct the local channel program 
to perform the erase/write function. 

The data in the buffer remains unchanged throughout the entire screen processing. 
Therefore, the user will probably want to edit his data to conform to the format of 
local 3270 data. 
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Defining Terminal Tables and Invitation Lists 

One TERMINAL macro instruction is required for each display or printer device. 
TERMINAL macros are not required for 3270 control units unless general polling is to 
be performed. The 3270 terminal types have been added to the list of terminals 
supported by TCAM on the TERM=type operand of the TERMINAL macro. (The 
ADDR=chars operand of the TERMINAL macro will be described in the next category 
on specific and general polling.) The coding of all other TERMINAL macro operands 
remains the same. 

TCAM invitation lists are required for 3270 support. There must be at least one entry 
in an INVLIST macro for each device to be invited under specific poll. There must be at 
least one entry in an INVLIST macro for each control unit when using general poll. 
(Coding the ORDER=(entry,...) of the INVLIST macro will be described in the next 
category on specific and general poUing.) The coding of all other operands of the 
INVLIST macro remains the same. 

Note: There must be a specific poll entry for every remote 3270 in the 
system whether polled or not; this means that there must be specific poll 
entries for printers as well as input devices. Under general poll, every device 
connected to a control unit under general poll must be represented in the 
invitation list. 



Specific and General Polling 



Each control unit has a one-character polling address and a one-character selec- 
tion address. Each display station or printer has its own one-character address for 
specific polling and selection, and all devices share a one-character address for 
general polling. See the Operational Sequences section of the IBM 3270 
Information Display System Component Description manual (GA27-2749). 

Double addressing is used for both control unit and device in the ADDR= ope- 
rand of the TERMINAL macro and the ORDER= operand of the INVLIST 
macro. Each five-character polling or selection sequence has the following format: 

xxxxyyyyENQ 

where xx is the hexadecimal representation in EBCDIC or ASCII of the control 
unit address for polling or selection, yy is the hexadecimal representation of the 
device address. ENQ is X*2D' for EBCDIC or X'05' for ASCII. Notice that in 
the above format the control unit and device addresses appear twice. The main 
difference in coding for specific or general polling is that specific polling does not 
require a TERMINAL macro for a 3270 control unit, and the INVLIST macro 
does not require a control unit entry in the ORDER= operand. 

General poll is a remote input technique for 2260 and 3270 remote devices in 
which special invitation characters are sent to a device control unit instructing that 
control unit to begin transmission from all devices ready to enter data. General 
poll may be conducted with programmed poll or Auto Poll. 

General poll begins with the sending of polling characters by the CPU. If a 
positive response is received from a terminal, TCAM determines the identity of 
the terminal originating the message. When an ETX is entered, a complete 
message has been received, and the contents of all buffers are ready to be sent to 
their destination. To receive the next message from the device control unit, 
TCAM begins a new input operation. Invitation characters are not retransmitted; 
instead the next message is read. This cycle continues until the device control unit 
indicates it has no more data by transmitting an EOT character. 
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No sending is allowed until the EOT character is received by the CPU. After that, 
TCAM either transmits or polls the next entry in the invitation Ust. 

The following examples show the difference between terminal tables and invita- 
tion lists for specific and general polling. They also illustrate the use of double 
addressing in the ADDR= operand of the TERMINAL macro and the ORDER= 
operand of the INVLIST macro. 

Sample terminal table for specific poll: 

TR3277A TERMINAL QBY=T,DCB=D327 1 ,RLN=1 ,TERM=327R, 

QUEUES=MO,ADDR=6060C1C12D 

TR3277B TERMINAL QBY=T, DCB=D327 1 ,RLN=1 ,TERM=327R, 

QUEUES=MO,ADDR=6060C2C22D 

TR3275A TERMINAL QBY=L,DCB=D3275 ,RLN=1 ,TERM=327S, 

QUEUES=DR , ADDR=6 1 6 1 40402D 

Sample invitation list for specific poll: 

INV327A INVLIST ORDER-( TR3277A+4040C1 C1 2D, TR3277B- 
4040C2C22D),EOT=37 

INV327B INVLIST ORDER=( TR3275A-C1 C1 40402D ) , EOT=37 
Sample terminal table for general poll: 

' CU3271 TERMINAL QBY=T,DCB=D327 1 ,RLN=1 , TERM=327C, 

QUEUES=MO 

TR3277A TERMINAL QBY=T,DCB=D3271 ,RLN=1 ,TERM=327R, 

QUEUES=MO,ADDR=6060C1C12D 

TR3277B TERMINAL QBY=T,DCB=D327 1 ,RLN=1 ,TERM=327R, 

QUEUES=MO,ADDR=6060C2C22D 

CU3275 TERMINAL QBY=L,DCB=D3275 ,RLN=1 ,TERM=327C, 

QUEUES=DR 

TR3275A TERMINAL QBY=L,DCB=D3275 ,RLN=1 ,TERM=327S, 

QUEUES=DR,ADDR=616140402D 

Sample invitation list for general poll: 

INV327A INVLIST ORDER=( CU327 1 +40407F7F2D, 

TR3277A+4040C1C12D, 
TR3277B-4040C2C22D ) ,EOT=37 

INV327B INVLIST ORDER=( CU3275+C1 C1 7F7F2D, 

TR3275A-C1C140402D),EOT=37 

3270 Display Station (Local) 

In coding the INVLIST, TERMINAL, and line group DCB macros for the 3270 
Local configuration, you may consider each 3270 Control Unit attached locally to 
be a line group, and each 3270 station attached to such a control unit as a line in 
that group; that is, you may code one DD statement and one line group DCB 
macro per control unit and one INVLIST macro per terminal. In addition, each 
3270 Local must be represented by a TERMINAL macro. 
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Issue one INVLIST macro instruction for each IBM 3270 Local; this macro must 
contain a single entry for the station. All 3270 Locals attached to the same IBM 
3270 Display Control Unit may be considered to be in the same line group, or 
each 3270 may be defined separately. The INVLIST macros for these stations 
must be specified in the INVLIST= operand of the Une group DCB macro accord- 
ing to ascending relative Une number. Relative line number for 3270 Local 
stations in the same line group is determined by the order in which their TERMI- 
NAL macros are arranged; see the description of the TERMINAL macro. 

The INVLIST entry for a 3270 Local should consist of the name of the station, a 
"+", and a one-byte code of X'02' (Read Buffer) or X'06' (Read Modified) 
indicating the type of read operation to be performed when data is entered at the 
station. 

Example: 

The following INVLIST macro is for a 3270 Local display device named DISPL 

L0CST1 INVLIST ORDER=( DISP1 +06 ) 

The 06 causes a Read Modified operation to be performed by TCAM when data is 
entered at the display device. 

Issue one TERMINAL macro for each 3270 Local. All TERMINAL macros for 
3270s on the same 3270 Control Unit must be grouped together. Assign a relative 
line number to each 3270 display device according to the position of its 
TERMINAL macro in the group; that is, in the first TERMINAL macro in the group 
enter RLN=1, in the second RLN=2, etc. 

Example: 

The following TERMINAL macro is the first in a group of macros representing 
3270 Local display devices attached to a 3270 Control Unit: 

TERM1 TERMINAL QBY=L,RLN=1 ,DCB=DCB3270L, TERM=327L 
QUEUES=MO 

The ADDR= operand of the TERMINAL macro is not meaningful for the 3270 
Local. One line group DCB macro instruction may be coded for each locally 
attached 3270 Control Unit. The INVLIST= operand should be coded so that the 
order in which the INVLIST macros for the display devices attached to the control 
unit are named in the operand corresponds to the order in which the TERMINAL 
macros are arranged for the display devices attached to the control unit. 
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Specify CPRI=S. Send priority for 3270 Locals is the same as that for non-switched 
contention stations, described in the transmission priority section of the chapter 
Defining Terminal and Line Control Areas, If the user has keyed in part of a message 
he wishes to enter, but has not actually entered it at the time TCAM sends a message 
to his display device, the message he is attempting to enter is erased from the screen 
and must be re-entered at a later time. 

Example: 

The following line group DCB is for an IBM 3270 Control Unit attached locally: 



DCB3270L DCB 



DSORG^TX , MACRF= ( G , P ) , CPRI=S , * 

DDNAME=DD3270L, INVLIST=( L0CST1 , , , * 

L0CST2, , ,L0CST3, , ),PCI( A,N), * 
BUFIN=1 , BUF0UT=2 , BUFSIZE=480 , BUFMAX=2 



The following DD statement would be included in the job control cards for the 
execute steps, if the 3270s were assigned addresses 150, 151, 152: 



//DD3270L 

// 

// 



DD UNIT=150 
DD UNIT=151 
DD UNIT-152 



Coding Considerations 



• The KEYLEN= operand of the INTRO macro must be greater than 43. 

• Buffered terminal support is not provided for the 3270. 

• Use of the BFDELAY= operand of the TERMINAL macro is invalid for a 3270. 

• The MSGLIMIT macro must be coded specifying a limit of one message when 
performing general or specific polling. This ensures that a response message is not 
erased before it can be read. 

• For local 3270s, PCI=(A,N) may be specified on the line group DCB. PCI=(A,A) is 
not supported for local 3270s. 

• Read Buffer is not supported for remote 3270s and if coded will cause an I/O error. 

• The default output command for local 3270s is Write (WDC). 

• The 3270 treats ETBs as ETXs. 

• The user must insert and check all message contents including commands. 

• Under general poll, initiate mode is not supported. 

• Logical message definition and mid-batch recovery are not supported for input 
received from terminals under general poll. 

• Lock mode is supported only with conversational mode. Extended lock mode is not 
supported. 

• Conversational mode is not supported by general poll. 



Error Handling for the 3270 



On errors, using remote 3270s, either the buffers or the message in which the error 
occurred are passed through the corresponding Message Handler, and error bits are set 
in the message error record. Next the SOH%R message is passed through the input 
Message Handler before any additional I/O activity is conducted on the line. 



The remote 3270 conveys device-dependent, error information in the SOH%R message. 
When TCAM perceives, by an abnormal response, that a 3270 error has occurred, a 
permanent error indication is set in the message error record, and the current operation 
is terminated. All buffers are sent to the Message Handler to allow execution of error 
handling macros in the inmessage or outmessage subgroup. No I/O is allowed on the 
line until TCAM has made one attempt to retrieve the SOH%R message. TCAM conducts 
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a specific poll of the device that indicated an error to retrieve the device status. The 

SOH%R message is passed through the input Message Handler as a text message, and the (i 

SOH% bit (bit 1 5) is set in the error record after recording on SYSl .LOGREC. ^ 



Dynamic Buffering for Local 3270 



SOH 


% 


E 


DLE 


SIX 


data 


DLE 


ETX 



TCAM recognizes the SOH%E and records the transparent data on SYSl .LOGREC. The 
EREP utility program may be used to print the SYSl .LOGREC file. Data is the value 
of the counters. 

See the IBM 3670 Brokerage Communication System Component Description manual, 
(GA27-3050) for the format of the data portion of the message and further information 
about the broadcast facility. 



Dynamic buffering may be used with local or remote 3270 devices. For local 3270 
devices TCAM will attempt to recover from channel program checks caused by failure 
of PCI buffering mechanism to provide buffers fast enough. When PCI=(A,N) is coded 
on the DCB macro for a local 3270 device, TCAM constructs an input channel program 
in which the PCI is enabled only on the first CCW. On this interrupt, BUFMAX/BUFIN 
buffers are allocated. If buffers are not allocated rapidly enough and a channel program 
check on an invalid TIC occurs, TCAM will restart I/O at the beginning of the channel 
program. Recovery will be attempted three times. 



3670 Brokerage Communication System 

• For the broadcast facility, TERM=367C should be coded on the TERMINAL macro. 
One broadcast terminal should be defined for each Hne with attached 3670s. This 
allows all 3670 terminals on that line to receive the data queued for the broadcast 
terminal. 

• If the TCAM message concentration facility is being used, the broadcast terminal 
macro must follow any TERMINAL macros defining the 3670s on the line as 
concentrators. 

• The broadcast terminal should not appear in the invitation list for the line. 

• The broadcast data is sent by a fast -select channel program. There is no checking or /^ 
error recovery procedures performed on broadcast data. ''4 

• The broadcast facility is invoked by coding the COMMBUF= operand on the INTRO 
macro and issuing a COMMBUF macro in an inheader or inbuffer subgroup (see the 
description of the COMMBUF macro). 

• Special OBR/SDR recording is provided for the IBM 3670 Brokerage Communication 
System. The 3670 maintains counters for its attached devices and for the communi- 
cations adapter. At the end of the day or when the counters overflow, the data in the 
counters is sent to the host CPU for recording on SYSl .LOGREC and bit 15 of the 
Message Error Record is set. Data from the counters is sent in the following message 
format: 

11111 n 11 



i 
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• All messages (good morning messages, error messages, messages switched to a 3670 
from other terminals, and operator control responses) sent to a 3670 must conform 
to the 3670 output message format. TCAM provides the CTBFORM macro to assist 
the user in formatting messages. See the description of the CTBFORM macro in 
Appendix J. 

Note: For operator control response messages, the EOT character that ends 
each response must be deleted if message concentration is being used. 

IBM 3780 Data Communication Terminal 

The 3780 Data Communication Terminal, with the exception of the Space 
Compression/Expansion function, is supported by OS TCAM. From the Com- 
munication Interface, the 3780 appears to the CPU or other terminal device to be 
similar to the IBM 2770 in operation. However, there is one important difference. 
The 3780, being a single input/output batch terminal, does not have component 
selection. If a component selection character is received by a 3780 that is a 
multipoint station, the terminal will not respond to that sequence. Therefore, for 
multipoint operation, the addressing and poUing sequence should not have compo- 
nent selection. For point-to-point operation, if the terminal receives the compo- 
nent selection character, the character will be folded and printed. (For further 
details on methods of specifying addressing and poUing sequences, see the descrip- 
tions of the TERMINAL and INVLIST macros in this manual). While access 
method programs do not support Space Compression/Expansion they will pass 
messages containing compressed data. The user's appUcation program must 
implement the actual processing to make this feature operational. 

Note: The coding of the TERMINAL macro for the 3780 is identical to 
that of the 2770. 

The TPEDIT Macro Instruction for the IBM 50 Magnetic Data Inscriber 

The IBM 50 Magnetic Data Inscriber (MDI) is a key-operated device that records 
data on cartridge-contained magnetic tape. (For a description of the IBM 50 
MDI, see the pubUcation IBM 50 Magnetic Data Inscriber Component 
Description , GA27-2725.) It enables the user to enter data from source documents 
to magnetic tape, which is then used to enter data into an IBM System/360 
through the IBM 2772 Control Unit. Data received from the IBM 50 MDI 
attachment to the IBM 2772 Multi-Purpose Control Unit contains MDI control 
characters; the TPEDIT macro allows the user to edit this data. 

The re-enterable editing routine is activated by the TPEDIT macro issued in an 
application program following a GET or a READ macro (it must not be issued in 
the MCP). This routine edits MDI control characters as specified by operands in 
the TPEDIT macro. One of the operands also specifies whether a user error-exit 
routine is to handle error records. If data is to be received from more than one 
IBM 50 MDI at a time in an appUcation program, a separate parameter list must 
be issued for each (described in more detail in Input to the TPEDIT Macro ) 
below. 
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TPEDIT Macro Format 



Name 


Operation 


Operands 


[name] 


TPEDIT 


MINLN=n 

,EDIT=/ EDITR \ 
1 EDITD f 

,RECFM=/U \ 

,ERROPT= j name ) 
\ IGNORE f 

,VERCHK=/VOKCHK | 
1 NOCHK r 

,REPLACE=/X'xx' ) 
( X'19' / 

,BUFFER=/YES \ 

1no / 



Is the name of the macro and is optional. If included, the name may be any 
symbol valid in the assembler language. 



MINLN=n 



EDIT= J EDITrI 
I EDITD j 



RECF1VI= 



{v} 



specifies the minimum acceptable length of an input record where n is replaced 
by the decimal number of bytes desired as a minimum. For EDIT=EDITD, SOR, 
and EOR, codes are excluded from the length; for EDIT=EDITR, SOR, and EOR 
are included in the length. This operand may not be omitted. 



Specifies the type of editing to be done. 

EDITR causes the input to be edited and the start-of -record (SOR) and end-of- 
record (EOR) delimiters to be retained as part of the output. 

EDITD causes the input to be edited and start-of -record and end-of -record 
delimiters to be delete^. EDITD is assumed if this operand is omitted. 

The edit consists of the following functions: records are extracted one at a time 
from the input area by scanning for the record delimiting codes (SOR and EOR). 
Duphcating (DUP) codes are replaced by the character(s) from the corresponding 
location of the record in the work area when control was last returned to the 
editing routine (true for all records except the first). Left-zero fields are right- 
adjusted, with leading zeros inserted where necessary. Left-zero start codes, 
group separator codes, and records containing a cancel code do not appear in the 
output stream. Line-control characters (ETB, ETX, STX, and DLE/STX) are 
always deleted if found in the input area. 



Specifies the format of the output from the editing routine. 

If RECFM=U is coded, no segment descriptor word is added to each record. 



i 
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ERROPT= 



- j name I 

\ IGNORE / 



VERCHK= 



VOKCHK 
NOCHK 



If RECFM=V is coded, a segment descriptor word is added to each record as 
shown (RECFM=V is assumed if this operand is not coded). 



■ Logical Record 



Segment Descriptor , 
Word 1 



nn 



bb 



data 



where nn (2 bytes) is the length of the logical record and bb (2 bytes) is 
binary zeros reserved for system use. 

This four-byte field is included in the record length returned to the user in a 
parameter list. 

This four-byte field must be allowed for by the user when determining the size of 
the work area (see a Input to the TPEDIT Macro below). 



Specifies whether a user error exit routine is provided to handle error records. 

name specifies the name of the user error exit routine to be entered when the 
editing routine detects logical errors or replacement characters in the record. 

IGNORE specifies that an error exit routine is not provided. The error conditions 
are to be disregarded and the record is to be passed to the user without being 
handled by an error exit routine. If this operand is omitted, ERROPT=IGNORE 
is assumed. 



(Valid only if ERROPT=nanie Is coded) 



Specifies whether the records are to be checked for verify OK (VOK) codes. 
NOCHK is assumed if this operand is omitted (subsequent records are not 
checked). 



If VOKCHK is specified and a record does not contain the verify OK code, the 
record is passed to the error exit routine. 

When the editing routine encounters an erroneous record and control passes to 
this user-supplied routine, register 13 contains the address of a 72-byte register 
save area aligned on a fuUword boundary, and register 1 contains the address of a 
two-word parameter Ust ahgned on a fullword boundary. The parameter Ust is 
defined as follows: 

Word Contents 

1 Record address 

2 Address of record length 

The record length includes the four-byte Error Description Word appended, as 
shown, to the data record. In addition, if RECFM= V is coded in the TPEDIT 
macro, the logical record length ( nn ) includes these four bytes when it is passed 
to the error exit routine. 
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If RECFM=V is specified: 



1^- 



Logical Record 



1 
1 


1 

1 
1 

1 


-^ 


Error Description ^ 

Word 


1 
1 i 

1 


1 

1 


^ 


nn 


bb 










data 



If RECFM=U is specified: 

I » 

Error Description ->| 

Word I 



1 


















data 



Logical Record 



The contents of the Error Description Word are shown below. Further informa- 
tion is contained in a later section, /^^Ai/z/yZ/ig Records in Error. 



REPLACE 






The error exit routine can be used to analyze and possibly correct a record that is 
in error. When control returns to the editing routine with a BR 14 instruction the 
user must set register 15 to zero if the erroneous record is to be bypassed. Regis- 
ter 15 must be set to a nonzero value in order to direct the editing routine to 
ignore an error in the erroneous record, and thereby process the record in the 
normal manner. Whether the record in error is accepted or bypassed does not 
change its effect on subsequent records. The Error Description Word is removed 
by the editing routine when control returns from the error exit routine. 



Specifies the code to be used as a replacement character when the editing routine 
detects a 2772 replacement character (EBCDIC SUB character, X'3F') in the 
input. X'19' is the assumed value (default) because it is an end-of-data (ED) 
signal for an IBM 50 MDI cartridge and therefore can never appear as a valid data 
byte. 



For REPLACE=X'xx\ the user can replace xx with any hexadecimal characters 
he chooses (note that xx must be enclosed in single quotes). Choices may be 
made from the code chart in Figure 58 with exceptions as noted below. 

BSC control characters should not be used as replacement characters if the data is 
to be transmitted by BSC facilities after editing. 

Hexadecimal characters representing special purpose MDI codes that should not 
be used as replacement bytes are: 



X'OO' 


(LZ) 


X'lE' 


(VOK) 


X'74' 


(P4) 


x'lr 


(DUP) 


X'3C' 


(RM) 


X'75' 


(P5) 


X'12' 


(LZS) 


X'71' 


(PI) 


X'76' 


(P6) 


X'18' 


(CAN) 


X'72' 


(P2) 


X'77' 


(P7) 


X'lD' 


(GS) 


X'73' 


(P3) 


X'78' 


(P8) 
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R;fc n 1 




00 




01 




10 




11 








Rife 9 "k 


00 


01 


10 


11 


00 


01 


10 


11 


00 


01 


10 


11 


00 


01 


10 


11 


Dirs ^/U 


•i. k^ 


Iff Hrv n 





1 


2 


3 


4 


5 


6 


7 


8 


9 


A 


B 


C 


D 


E 


F 


































0000 







LZ 










Space 


& 


Minus 





















0-8-2 







0001 


1 




DUP 










/ 


PI 










A 


J 




1 


0010 


2 




LZ 
Start 












P2 










B 


K 


S 


2 


0011 


3 
















P3 










C 


L 


T 


3 


0100 


4 
















P4 










D 


M 


U 


4 


0101 


5 
















P5 










E 


N 


V 


5 


0110 


6 
















P6 










F 


O 


w 


6 


0111 


7 
















P7 










G 


P 


X 


7 


1000 


8 




CAN 












P8 










H 


Q 


Y 


8 


1001 


9 




ED 






















1 


R 


z 


9 


1010 


A 










<? 


I 






















1011 


B 












$ 


/ 


# 


















1100 


C 








RM 


< 


* 


% 


@ 


















1101 


D 




GS 






( 


) 


Under- 
line 


Prime 


















1110 


E 




VOK 






+ 


; 


> 


= 


















nil 


F 










1 


— 1 


? 


" 




















t t 

Bits 2nd Hex 
4,5 Digit 
6J 


































IBM 50 Code 
Name 


EBCDIC Code 
Name 




IBM 50 Code Name 
(See Note) 




LZ (LZ Fill) 
DUP 
LZ Start 
CAN (Cancel) 


NULL 
DC 1 
DC 2 
Can 


PI (Prog 1) 
P2 (Prog 2) 
P3 (Prog 3) 
P4 (Prog 4) 


ED (End Data) 
RM (Rec Mark) 
GS (Group Sep) 
VOK (Ver OK) 


EM 
DC 4 
IGS 
IRS 


P5 (Prog 5) 
P6 (Prog 6) 
P7 (Prog 7) 
P8 (Prog 8) 










No 


te: Codes are assigned for IBM 50 use only. 



















Figure 58. IBM 50 MDI Control Codes 
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BUFFER=/ yes) 
) NO 



This operand specifies whether the user's data is in BTAM buffers. TCAM users 
should either omit this operand or code BUFFER=NO. 

Input to the TPEDIT Macro 

Register 1 must point to a four- word parameter Hst (aUgned on a fuUword bound- 
ary) containing: 

Word Contents 

1 Input Address 

This is the address of the data to be edited. 

2 Input Length 

This is the length of the data to be edited. 

3 Edit work area address 

The work area required by the editing routine for a given parameter Ust is 
obtained in either of two ways. The work area can be provided by the 
editing routine (by an unconditional GETMAIN), or it can be provided by 
the user. 

If the work area is to be provided by the editing routine, this word must 

contain binary zeros. The editing routine issues a GETMAIN macro to 

obtain the required storage, and places the address of the storage obtained in ^ 

this word. If the work area is provided by the user, then this word contains ^i 

the address of the area supplied. 

The amount of storage needed, in addition to the fixed amount required, is 
determined from: 

a. the maximum record length; 

b. whether a user exit exists (72 bytes for a register save area and four 
bytes for an EDW are required by the macro if an exit is specified) ; 

c. whether variable record formats are used. 

The size (in bytes) of the work area may be determined from the formula: 

S= 84 + 76E + R + 4V 

where 

S is the size (in bytes) of the work area 

E=0 if ERROPT=IGNORE is coded 

E=lif ERROPT=name is coded 

V=Oif RECFM=U 

V=lifRECFM=V 

R is the length of the longest record to be processed 

4 Maximum record length ■ 
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Return Codes 



This is the length, in bytes, of the longest valid edited record. For 
EDIT=EDITD the length should exclude SOR and EOR codes; for 
EDIT=EDITR, the length should include SOR and EOR codes. 

The value of the maximum record size should not include the f our-byt^ 
Segment Descriptor Word added to a variable length record. 

Records that exceed the maximum record size are considered error records. 

Register 13 must contain the address of a 72-byte register save area aligned on 
a fullword boundary. 

After the editing routine has edited a record, it provides a return code in register 
15 indicating record availability and status of the input area, before returning 
control to the user. The return codes and their meanings are: 

Code 

(hex) Meaning 

00 A record is available; input area is empty. The routine has edited the last 
logical record in the input area and is passing the record to the user. 

04 A record is available; input area is not empty. The routine has edited one 

logical record and is passing that record to the user. 

08 No record is available; input area is empty. The last record in the input 

area was incomplete; that is, it was a partial record. 

OC End-of-data (ED) code was detected. 

For return codes 00 and 04, the record address and the address of the record 
length are given to the user in a two- word parameter Ust aligned on a fullword 
boundary. The address of the parameter Hst is returned in register 1 . The 
parameter Ust has the following format: 

Word Contents 

1 Address of the record 

2 Address of the record length 

Identifying Records In Error 

This section describes what the editing routine considers to be records in error. 
Once a record is determined to be in error, the editing routine passes the record to 
the user error exit routine, if ERROPT=name is specified in the TPEDIT macro 
statement. If an error exit routine is not specified, the erroneous record is returned 
as usual to the user. 

The editing routine maintains information about each record as it is being edited. 
This information is summarized in the Error Description Word (EDW) described 
below. When the EDW contains a nonzero value in either the level status (byte 0) 
I or the type status (byte 1), the record is considered an erroneous record, and the 

EDW is inserted between the four-byte record length field and the data portion if 
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Level Status (Byte 0) 



RECFM= V is specified in the TPEDIT macro. Otherwise, the EDW is added to 
the start of the record to aid the user in analyzing the error. Format of Error 
Description Word for the TPEDIT Macro 

Byte Level Status 

- for any error record that will not cause questionable data to be in the 

following record(s). 

1 - for any error record that may cause questionable data to be in the 

following record(s). 

2 - for any error record that ( 1 ) contains questionable data due to the error 

level of preceding record(s) and (2) may cause questionable data to be 
in the following record(s); and where the level status of the previous 
record was either 1 or 2. 

Byte 1 Type status 

- No identifiable error(s) 

1 - Start-of -record (SOR) or end-of-record (EOR) in error 

2 - Length error 
4 - Field error 

8 - Data check error 

This field may contain combinations of these error types; for example, a C 
(hexadecimal) indicates a data check error and a field error. 



none of the preceding levels. Start-of -record 
(SOR) is in error. 



Byte 2 


Program Level 


1-Pl 


5-P5 ] 


2-P2 


6-P6 


3-P3 


7-P7 


4-P4 


8-P8 



Byte 3 Record Status 

U - Unverified record 

V - Verified record 

E - Neither U nor V. End-of-record (EOR) is in error. 

The error description record is in EBCDIC format. For example, a 2 is represent- 
ed as X'F2'; a C is represented as X*C3'. 



The level status indicator identifies erroneous records that result from interrecord 
dependency and that cannot be identified in the type status byte. 

The level status is presented with each error record and has a value of: 

For any error record that will not cause questionable data in following 
record(s). 

1 For any error record that may cause questionable data in following record(s), 
where the level status of the previous record was zero. 



( 
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Type Status (Byte 1) 



2 For any error record that has questionable data because of the error level of 
preceding record(s) that may cause questionable data in the following 
record(s),and where the level status of the previous record was either 1 or 2. 

A level status other than zero is presented with error records resulting from the 
following: 

• The start-of -record (SOR) location has a character defined as an error. 

• The record contains two or more data check bytes in succession. 

• The record is longer than the user-specified maximum length record. 

• The length of the record is not equal to the length of the first valid record of the 
same program level encountered on the MDI cartridge from which data is being 
obtained. 

• The record has a data duplication dependency on a previous record with one of 
the foregoing. 

The level status is set to zero when the editing routine encounters a record without 
one of the previous errors, a canceled record, or the first record of a cartridge. 



The type status indicator identifies records in error because of SOR, EOR, length, 
field, and/or data check error conditions. 

The type status is presented with each error record and has a value of: 

For any record that has no identifiable error(s), but contains questionable data 
because of a level status of other than zero (see Level Status). 

1 For any record that has an SOR character of other than PI through P8 or a GS 
code; or that has an EOR character of other than a VOK code when the user 
has specified VERCHK= VOKCHK; or that has an EOR character of other 
than a VOK code or RM code when the user has specified 
VERCHK=NOCHK. 

2 For any record that has an incorrect length because it is: 

• longer than the specified maximum, or 

• shorter than the specified minimum (MINLN), or 

• not equal to the length of the first valid record of the same program level 
encountered on the MDI cartridge from which data is being obtained. 

4 For any record that has one or more field error(s). A field error is duplication 
and/or left-zero justification functions that did not occur due to an error 
condition. 

8 For any record that has a data check error. 

The type status indicator can also have hexadecimal values of 3, 5, 6, 7, 9, A, B, 
C, D, E, and F. These values indicate various combinations of SOR, EOR, length, 
field, and data check errors. For example, a value of A indicates a record with a 
data check error (8) as well as an incorrect length (2). 

A data check error is indicated by the presence of 2772 as replacement characters 
(EBCDIC SUB character, X'3F') in the input. 
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Program Level (Byte 2) 



This byte contains an indication of the start-of -record (SOR) character associated 
with this record. 



Record Status (Byte 3) 



This byte contains an indication of the end-of-record (EOR) character associated 
with this record. 



Sample Records Containing Errors 

These records show some of the errors that may occur during processing and their 
effect on the Error Description Word (EDW). For these records, the maximum 
record length is specified as 50; EDITR and VOKCHK are specified, and the 
hexadecimal REPLACE character is '5B' ($). An asterisk in the records indicates 
the presence of a DUP code in the location before editiilg. 

Record 1 was a valid record. It contained a program level 1 code and thus 
estabUshed the valid length for all program level 1 records received from the 
cartridge. 

Record 2 has a data check in the SOR location. Level status is set to 1 because 
the SOR location might have contained a cancel code that would cause any data 
dupHcated into the following record to be questionable. 



Record 3 has no identifiable error but may contain questionable data because it 
contained DUP codes and follows a record with a level status of 1 . 

(Record 2) 



19EV 


*************** 
$111378 RECORD NUMBER 


V 

*o 

2AK 


(Record 3) 


201V 


p *************** 
1357987 RECORD NUMBER 


V 

*o 

3AK 


(Record 4) 


081V 


P 

1358977 REC$RD NUMBER 


V 



4AK 


(Record 5) 


131U 


P 

1358436 RECORD NUMBER 


R 

5M 


(Record 6) 


241V 


p *************** 
1358436 RECORD NUMBER 


V 

*o 

6$K 



622 OS/MFT and OS/MVT TCAM Programmer's Guide 



(Input record 7) 



233E 



3998865 RECORD NUMBER 7A MAXIMUM 00001430 IN WAREH 



V 

O 

OUSEK 



y- 

(Error record 7) 



(Error record 8) 



21 EV 



V 



OUSEK 



(Input record 8) 
(Error record 9) 



V 
P O 

1367 $82 RECORD NUMBER 8AK 



081V 

Resulting Error Description Word 



Programming Considerations 



Record 4 has a data check error. Because it contained no DUP codes, the level 
status is set to 0. 

Record 5 is shorter than first program level 1 records received from the cartridge 
(length error). This record also contains an RM code rather than a VOK code in 
the EOR location (VOKCHK was specified). Because the editing routine cannot 
determine why the record is short, all data duplicated from this record is question- 
able; therefore, the level status is set to 1. 

Record 6 contains a DUP code that is beyond the last position of the preceding 
record. 

Record 7 is longer than the maximum specified record length. Note that it is 
passed as two records. The first record indicates an EOR error and a length error; 
the second indicates an SOR error. 

Record 9 has a data check error. Because it contained no DUP codes, the Level 
Status is set to zero. 



All canceled records are bypassed and are not passed as erroneous records. 

All input records less than three bytes in length (SOR location, one data 

byte, EOR location) are treated as canceled records. An input record of this 

size may be the remaining portion of a record that was longer than the 

maximum user-specified record size. 

Data duplication occurs with the DUP code replaced by the character from 

the corresponding location of the previous record in the work area when 

control was last returned to the editing routine. 

Data dupUcation does not occur and the DUP code is replaced with the 
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user-specified error replacement character, and a field error is indicated, for 
any of the following conditions: 

The DUP code is encountered in the first record of a cartridge. 

The DUP code is encountered in a record and previous record was a 
canceled repord. 

The DUP code is encountered in a record and its position would cause 
duplication of the previous record's end-of-record delimiter location or a 
position beyond the length of the previous record. 

• Left-zero justification does not occur, the left zero fill code (LZ) is replaced 
with the user-specified error replacement character, and a field error is 
indicated, for either of the following conditions: 

The left-zero fill code (LZ), is encountered without its corresponding 
left-zero start code (LZS). 

The user-specified maximum record size is exceeded before encountering 
the valid end of a left-zero field. 

• For BTAM users using dynamic buffering, the BSC control characters ETB 
and ETX should not be entered as data on IBM 50 MDI cartridges. 

End-of-Cartridge Code 

A unique code, written by the IBM 50 MDI, is used to signal to the 2772 control 
unit that all meaningful data on a cartridge has been read. For the MDI cartridge, 
the end-of-cartridge code is the ED character (X49'). 

After initiation of a Read operation the MDI continues to read data from the tape 
until it senses the ED character. When the MDI sends this character to the 2772, 
the 2772 signals the tape to rewind and transmits the data in its buffer to the 
computer. 



{ 
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Appendix H. Conserving Main Storage 



Several operands of the INTRO macro instruction can be used to reduce the 
amount of main storage required by a TCAM MCP. 

If disk queuing is not needed, specifying DISK=NO results in a saving of 140 
bytes. 

When disk queuing is required CPB=1 saves 730 bytes in addition to the actual 
amount of storage required for the CPBs. 

If the system interval is not required, specifying INTVAL=0 will save 660 bytes. 

If ENVIRON = TCAM and the system configuration permits, specifying the 
LINETYP= operand as something other than LINETYP=BOTH results in a 
considerable saving. The number of bytes saved is: 

LINETYP=BISC2110 
LINETYP=STSP4220 
LINETYP=MINI6720 

If ENVIRON= does not specify TCAM or MIXED, specifying LINETYP=STSP will result 
in a saving of 4220 bytes. 

If the system timer feature is not required, specifying FEATURE =(„NOTIMER) 
saves 820 bytes. 

If ENVIRON = TCAM, the other suboperands of the FEATURE = operand will 
also reduce main-storage requirements. FEATURE=(DIAL,N02741) saves 70 
bytes. FEATURE=(NODIAL,N02741) saves 420 bytes. However, 
FEATURE=(NODIAL,2741) does not result in a saving. 

The use of the USEREG=, DTRACE=, OLTEST= and COMWRTE= operands 
increases the amount of main storage required by the MCP. DTRACE= requires 
an additional amount of main storage equal to the value specified multiplied by 
four. OLTEST= requires IK of main storage for each integer specified (that is, if 
OLTEST=10 is coded, an additional lOK of main storage is implied). For a 
discussion of the effects on storage requirements of COMWRTE=, see the section 
Debugging Aids in Using TCAM SERVICE Facilities as well as the OS 
Storage Estimates manual (GC28-6551). For a discussion of the use of the 
USEREG= operand and its effects upon storage requirements, see User Code in 
a Message Handler in the chapter Designing the Message Handler . 

The WTTONE= operand will require an additional n-i-2 bytes of main storage, 
where n is the integer specified for WTTONE=. 

In addition to the INTRO operands, operands of the DCB, TERMINAL, and 
TPROCESS macros, in conjunction with INTRO, may have an effect upon the 
amount of main storage required for the MCP. 

If dynamic allocation of buffers is not required, and all DCB macros specify 
PCI=(N,N), 930 bytes are saved. The queuing type specified on the TERMINAL 
and TPROCESS macros, in conjunction with the MSUNITS= and DISK= 
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operands of the INTRO macro, changes the amount of main storage required. If 
reusable disk queuing or multiple queue types are used, an additional 3510 bytes 
are needed. Disk queuing only saves 3300 bytes over a combination of disk and 
main-storage queuing. Main-storage-only queuing saves 4110 bytes over a 
combination of disk and main-storage queuing. 

The amount of main storage required may also be reduced by proper specification 
of buffers and buffer units. Specification is provided in the INTRO operands 
LNUNITS=, MSUNITS=, and KEYLEN=, and the DCB operand BUFSZ=. A 
checklist for determination of proper size for the application is found in Design 
Considerations in Defining Buffers . The use of these operands depends on the 
requirements of the application. It may not be possible to utilize all of the savings 
possible in a particular application. 

The operands and number of bytes saved are suitimarized in the following chart: 



Macro 


Operand(s) 


Bytes Saved 


INTRO 


DISK=NO 


140 




CPB=1 


730 




INTVAL=0 


660 




LINETYP=BISC 


2110 




LINETYP=STSP 


4220 




LINETYP=MINI 


6720 




FHATURE= („NOTIMER) 


820 




FEATURE= (DIAL,N0274 1 ) 


70 




FEATURE= (NODIAL,N0274 1 ) 


420 




MSUNITS=n,DISK=NO 


4110 




MSUNITS=0,DISK=YES 


3300 


DCB 


PCI=(N,N) 


930 



i 
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Appendix I: Macro Instructions for Time-Sharing Support 
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Macro Instructions for Time-Sharing Support 

This appendix describes additional macro instructions and changes to TCAM 
macro instructions for the system programmer who incorporates the IBM 
System/360 Operating System Time Sharing Option (TSO) into his system. It is 
intended primarily for the system programmer who elects to design his own TSO 
Message Handler. A summary of MH design considerations is contained below in 
the section TSO /TCAM Mixed Environment . 

TSO provides general-purpose time-sharing facilities in a System/360 Operating 
System MVT environment. TCAM is the access method that controls I/O 
operations for the TSO user. The OS pubUcation TSO Guide describes the 
concepts, features, and implementation of TSO and should be consulted for 
designing, generating, or maintaining a TSO installation. 

TSO jobs may be run in either of two environments, TSO-only or TSO/TCAM 
mixed environment. 

Operating in a TSO-Only Environment 

In a TSO-only environment, time-sharing (or foreground) operations can take 
place concurrently with the execution of standard batch jobs ( background); thus, 
the system need not be dedicated to time sharing. All terminals that are logged on 
for a time-sharing session in a TSO-only environment are dedicated to TSO 
Message Handlers during the session. The system programmer who is designing 
such a system should consult the TSO Guide for guidelines in generating his 
IBM-supplied MCP. The LINEGRP, LISTTA, and TSOMCP assembly language 
macros, described in the TSO Guide , are used to define line configuration, 
terminal characteristics, and any optional features the user wished to include in his 
system. 

Operating in a TSO/TCAM Mixed Environment 

When operating in a mixed environment, TCAM and TSO tasks concurrently 
share all necessary system resources. 

The system programmer provides his own MCP and is responsible for activating 
and deactivating the system, defining terminal and line control areas, and defining 
data sets. Optionally, he is relieved of the task of designing his MH routines for 
handUng TSO messages by specifying an IBM-provided MH routine with the 
TSOMH macro (described in the TSO Guide ). He is still responsible for design- 
ing his TCAM Message Handlers. The remainder of this appendix is intended 
primarily for the system programmer who designs his own TSO Message Han- 
dlers; it is assumed that he is already familiar with the MCP and MH design 
considerations and macro capabilities presented in eariier sections of this 
publication. 

Changes to TCAM Macro Instructions 

Four TCAM macros are modified for TSO support: 

. INTRO 

. TERMINAL 

• line group DCB 

. STARTMH 

This section provides a general statement on the function of each macro that it 
discusses, and specific statements on operands affected by TSO. See other 
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INTRO Macro Instruction 



chapters in this publication for detailed discussions of the functions of these 
macros in TCAM environment. 



This macro is described in the section Activating and Deactivating the Message 
Control Program . The INTRO macro establishes addressabiUty, performs 
initiaUzation functions, and generates the TCAM constant and work area called 
the address vector table. This macro must be included in a mixed environment. 
The following operands are added or affected by time-sharing support. 



Name 


Operation 


Operand 


[symbol] 


INTRO 


ENVIRON=(TSO J 
] MIXED [ 
'TCAM ' 

,CPB=( integer ) 

,MSMIN= I integer 

,MSMAX= ( integer) 
J70 \ 

,MSUNITS= 4 integer < 










,FEATURE=( JNODIAl/, 


JN0274l/, 


jnotimer/ ) 






Jdial ( 


)2741 j 


/TIMER ( 



ENVIRON= (TSO 

^ MIXED 
/TCAM 



This keyword operand is added to INTRO. 

Response Keyword: None. 

Function: Specifies whether this MCP is dedicated to either TSO or TCAM 

functions, or both. 

Default: ENVIRON=TCAM 

Format: TSO, MIXED, or TCAM 

Notes: TSO specifies that this MCP is dedicated to time-sharing functions. This 

keyword value causes the assembly of a smaller version of the address vector table 

and sets a bit in the table indicating that only TSO Message Handlers can be used 

in this MCP; it also causes the inclusion of required time-sharing subtasks and the 

exclusion of disk and main-storage-queuing subtasks and other subtasks not used 

for time sharing. 

MIXED specifies that this MCP supports all required TCAM and TSO functions. 
This keyword value causes the assembly of the full version of the address vector 
table and sets bits in the table indicating that both TCAM and TSO Message 
Handlers can be used in this MCP; it also causes the inclusion of all required 
time-sharing subtasks. 
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CPB=( integer 



{integer ) 
S 



Response Keyword: D= 

Function: Specifies the number of channel program blocks to be provided for 

transferring data between buffer units and message queues maintained on disk. 

Default: CPB=0 

Format: Unframed decimal integer. 

Maximum: 65535 

Notes: If ENVIRON=TSO is specified, this operand is ignored, and a WTOR 

response at INTRO execution time should not be entered. Such a response causes 

the following message to be returned to the system console: 



IED003A INVALID KEYWORD xxx 



MSMIN: 



{integer } 
50 S 



where xxx is replaced by CPB= or D=xx. Reenter all valid entries that were 
initially entered after this invaUd entry (do not reenter the invahd entry). See 
additional notes at the description of the CPB= operand of the INTRO macro. 



Response Keyword: Y= 

Function: Specifies the percentage of units enqueued on a message queues data 

set (specified by the MSUNITS= operand) below which a bit is set in every 

message error record in the system. 

Default: MSMIN=50 

Format: Unframed decimal integer. 

Maximum: 99 

Notes: If ENVIRON=TSO is specified, this operand is ignored, and a WTOR 

response at INTRO execution time should not be entered. Such a response causes 

the following message to be returned to the system console: 



IED003A INVALID KEYWORD xxx 



{integer ) 
70 S 



MSMAX=5 integer 
70 



where xxx is replaced by MSMI or Y=xx. Reenter all valid entries that were 
initially entered after this invaUd entry (do not reenter the invalid entry). See 
additional notes at the description of the MSMIN = operand of the INTRO macro. 



Response Keyword: X= 

Function: Specifies the percentage of the number of units (specified by the 

MSUNITS= operand) to be enqueued on a main-storage message queues data set 

before a warning is provided that the data set is nearly full. 

Default: MSMAX=70 

Format: An unframed decimal integer greater than zero. 

Maximum: 100 

Notes: If ENVIRON=TSO is specified, this operand is ignored, and a WTOR 

response at INTRO execution time should not be entered. Such a response causes 

the following message to be returned to the system console: 



IED003A INVALID KEYWORD xxx 



where xxx is replaced by MSMA or X=xx. Reenter all valid entries that were 
initially entered after this invalid entry (do not reenter the invalid entry). See 
additional notes at the description of the MSMAX= operand of the INTRO 
macro. 



i 
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1VISUNITS= 



! integer ) 
( 



Response Keyword: M= 

Function: Specifies the maximum number of buffer units that may be assigned to 

the main-storage message queues data set at any one time. 

Default: MSUNITS=0 

Format: Unframed decimal integer. 

Maximum: 65535 

Notes: If ENVIRON=TSO is specified, this operand is ignored, and a WTOR 

response at INTRO execution time should not be entered. Such a response causes 

the following message to be returned to the system console: 



FEATURE=(J NODIAL } 
I DIAL ) 



\N02741 

/2741 



1 ■ 



^NOTlMERn 
) TIMER ) 



TERMINAL Macro Instruction 



IED003A INVALID KEYWORD xxx 

where xxx is replaced by MSUN or M=xx. Reenter all valid entries that were 
initially entered after this invalid entry (do not reenter the invaUd entry). 

If ENVIRON=MIXED is specified, either the MSUNITS= operand must specify 
a nonzero value, or DISK= YES must be specified. 

See additional notes at the description of the MSUNITS= operand of the INTRO 
macro. 



Response Keyword: None. 

Function: Specifies additional features to be supported in the TCAM system. 

Default: FEATURE=(DIAL,2741, TIMER) 

Format: NODIAL or DIAL, N02741 or 2741, and NOTIMER or TIMER. 

Framing parentheses must be coded. If a suboperand other than the last is 

omitted due to default, a comma must be coded to indicate that it is missing. 

Notes: If the ENVIRON= operand specifies either TSO or MIXED, do not 

specify the N02741 keyword value. See additional notes at the description of the 

FEATURE= operand of the INTRO macro. 



This macro is described in the section Defining Terminal and Line Control 
Areas . The UTERM=NO operand generates an entry other than a line entry in the 
terminal table and defines parameters for the station with which it is to be associ- 
ated; there must be one such TERMINAL macro instruction defined for each 
station attached to a nons witched line. The UTERM=YES operand generates a 
Une entry in the terminal table and defines parameters for all stations that can dial 
into a particular line and that do not uniquely identify themselves. The following 
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TERM=type 



QBY=T 



QUEUES=form 



operands are either expanded or added for time-sharing support: 


Name 


Operation 


Operand 


symbol 


TERMINAL 


TERM=type 
[,QBY=T] 
,QUEUES=form 
[,SCRSIZE=(n,m)] 

[,feature=/ break ' , "attn ' ,[tosuppr] \ ] 
vLnobreakJ LnoattnJ ) 



Function: Specifies the terminal type. 

Default: None. This operand must be specified. 

Format: The values that can be specified to indicate TSO terminals in either a 

mixed environment or a TSO environment are either 1050, 2741, 226L, 226R, 

2265, 3335, 5041, 327L, or 327R. 

Notes: The value 5041 is added for TSO support indicating that both the IBM 

2741 Communication Terminal and the IBM 1050 Data Communication System 

may be supported by this terminal table entry. The 5041 keyword value is 

supported only on switched lines. 

When a group of terminals is defined by UTERM=YES, there is only one symbol- 
ic name associated with all the terminals on that line. This symbolic name can be 
used during an on-line test by TOTE in its scheduUng and control functions, if all 
terminals on the line are the same type (that is, line control is the same for all 
terminals, all terminals have the same hardware features, and the configuration of 
peripheral equipment is identical for all terminals). 

Where terminals on a line are not of the same type (such as the 2741/1050 
configuration described above), a separate TERMINAL macro, whose UTERM= 
operand specifies YES, must be coded for each group of terminals that are of the 
same type. These additional TERMINAL macros provide additional symbolic 
names needed by TOTE for scheduling and controUing on-line tests for unlike 
terminals. 



Function: Specifies the type of message queuing. 

Default: None. Must be specified for TSO or non-dedicated multipoint terminals. 

Format: QBY=T 



Function: Specifies where the message queues are to be maintained. 

Default: None. This operand must be specified. 

Format: TS, DRT, DNT, MOT, MRT, or MNT 

Notes: One of these values is added to specify where the message queues are to be 

maintained when time-sharing subtasks may be supported in the TCAM system. 

TS indicates time-sharing use only, and requires that the ENVIRON = operand of 

the INTRO macro must specify either TSO or MIXED. 
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SCRSIZE=(n,iii) 



QUEUES=TS causes the generation of a shorter destination queue control block, 
which can be used only to support time sharing on this station. When TS is 
specified and a queuing operand of L is specified on the QBY= operand of the 
TERMINAL macro, the LEVEL= operand of the TERMINAL macro is ignored. 

If QUEUES=TS is specified, DIALNO=NONE is assumed for this TERMINAL 
macro (that is, there is no dial out to the time-sharing terminals represented by 
this TERMINAL macro). The keyword values of the QUEUES = operand have 
been expanded to allow definition of non-dedicated terminals. The first two 
letters of the keyword values are explained in the definition of the TERMINAL 
macro instruction in the Defining Terminal and Line-Control Areas section. 
The additional value T indicates that time sharing may also be supported from 
this terminal. Specifying one of these keyword values defines a non-dedicated 
terminal. These keyword values ending in T are restricted to a mixed environment 
(see TSO/TCAM Mixed Environment in this appendix). The following chart 
should be helpful in choosing the appropriate QUEUES = operand for the 
TERMINAL macro. 



QUEUES = 

Operand on 

Terminal 

Macro 


Type of 

Environment 

Supported 


Type of 
Terminal 


Message 
Handler 


TS 


TSO 

Mixed 


Dedicated 


TSOMH 


DR; DN; MO 
MR;MN 


TCAM 


Dedicated 


TCAM MH 


DRT; DNT; MOT 

MNT; MRT 


Mixed 


Non-Dedicated 


TSOMH 
TCAM MH 



Function: Specifies the correct number of rows and characters per row for screens 

of TSO display stations. 

Default: None. This operand must be specified if display stations are used. 

Format: Decimal integers of 1 or greater, enclosed in parentheses and separated 

by commas. 

Maximum: 255 each. 

Notes: n is replaced by the number of rows on the display screen being used, m 

is replaced by the number of characters per row allowed for the display screen 

being used. The component description SRL for the device used provides the 

correct values that must be specified. TCAM ignores this operand if it is specified 

for a station that is not a TSO display station. 



FEATURE=/ [break 1 , 

VInobreakJ 

[attn 

NO ATTN I 



[TOSUPPR] \ 



Function: Specifies featues for TSO terminals. 
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Default: Depends on terminal type specified on the TERM= operand (values 
listed in the illustration below). 

Format: BREAK or NOBREAK, ATTN or NO ATTN, and TOSUPPR 
Notes: The characteristics defined by this operand have meaning only during the 
duration of a time-sharing session. The reverse break and time-out suppression 
features can be changed during execution of a time-sharing session using TSO 
commands from the terminal or terminals that are defined in TCAM by 
TERMINAL macro instructions (TSO commands are described in the OS pubUca- 
tion TSO command Language ). 

Figure 59 illustrates the hardware features that are either required, optional, or 
invaUd for terminals that are specified on the TERM= operand of the 
TERMINAL macro. Each feature that can be specified by the FEATURE= 
operand is discussed following the illustration. 

BREAK indicates that the terminal has the reverse break feature; that is, it can be 
taken out of transmit mode by the computer. It also indicates that the TPUT 
macro used with the break option is supported on this terminal (the TPUT macro 
instruction transfers data from a caUing program to the time-sharing control task 
region — see Terminal I/O in the TSO Guide). Use of the TPUT macro with 
the break option is not supported unless BREAK is either specified or assumed as 
a default value. 



Features 


Value specified 
on FEATURE = 
operand of the 
TERMINAL macro 


Value specified on the TERM = operand of the TERMINAL macro 


1050 


2741 


5041 


226L, 

226R, 2265, 
327L, or 
327R 


3335 


(IBM 1050) 


(IBM 2741) 


Break feature 


BREAK 


Optional 


Optional 


Optional 


Optional 


invalid 


Required2 


NOBREAK 


Optional^ 


Optional 


Optional^ 


Optional 3 


Required 


Invalid 


Attention feature 


ATTN 


Optional^ 


Optional^ 


Optional^ 


Optional 


Invalid 


Required2 


NOATTN 


Optional 


Optional 


Optional 


Optional 


Required 


Invalid 


Time out suppression feature 


TOSUPPR 


Optional 


Required2 


Optional 


Required2 


Invalid 


Required2 



Notes: 

1 . If neither BREAK nor NOBREAK is specified, the system defaults to the 
value of BREAK 

2. The system assumes that this feature is present even if it is not 
specified on the FEATURE = operand of the TERMINAL macro, 

3. If neither BREAK nor NOBREAK is specified, the system defaults to the 
value of NOBREAK. 

4. If neither ATTN nor NOATTN is specified, the system defaults to the 
value of ATTN. 

5. Use of the attention key on the IBM 1050 without the text time-out suppression 
feature is valid only during output; however, an attention interrupt can be 
simulated during input by entering an EOT without a preceding CR. Use of the 
attention key is valid on input or output with a 1050 having the text time-out 
suppression feature. 

Figure 59. Required, Optional, and Invalid Features for TSO Terminals 



i 
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NOBREAK indicates that the terminal does not have the reverse break feature. 

ATTN indicates that the terminal has the attention interrupt feature; thus, it can 
interrupt the CPU while it is accepting data. 

NOATTN indicates that the terminal does not have the attention interrupt 
feature. 

TOSUPPR specifies that an IBM 1050 terminal has an optional time-out suppres- 
sion feature and that an INHIBIT channel command can be used safely with it. 
INHIBIT channel commands are always used in a time-sharing session with the 
IBM 2741 Communication Terminal and AT & T Models 33 and 35 
Teletypewriter Terminals (switched). 



Line Group DCB Macro Instruction 

This macro is described in the section Defining the MCP Data Sets . The line 
group DCB macro with a DSORG= operand that specifies TX defines each line 
group data set. The following operands are either modified or affected by time- 
sharing support. 



MH=nihname 



Name 


Operation 


Operand 


linedcb 


DCB 


MH=mhname 
,CPRI=( R) 

[,TRANS=< table ( ] 
' list ' 



Alternate Source: None. 

Function: Specifies the name of the time-sharing MH or TCAM MH (mixed 

environment) for the line group represented by this DCB macro. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols, and must be 

the same as the name specified in the name field of a STARTMH macro. 

All time-sharing buffers are handled as if LC=IN, and CONV=YES are specified 
on the STARTMH macro regardless of how STARTMH is coded. This operand 
must be coded such that a time-sharing MH may be reached from Une groups 
handling time-sharing terminals or line groups handling non-dedicated terminals. 
The decision to make terminals dedicated or non-dedicated is made by the choice 
of keyword values for the QUEUES= operand of the TERMINAL macro (see 
chart following the descriptions of the TERMINAL macro and TSO/TCAM 
Mixed Environment in this appendix). 



I 



CPRI=( R 
E 

S 



Alternate Source: PP,OE,DD. 

Function: Specifies the relative transmission priority assigned to the lines in this 

Une group. 
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TRANS= 



■\ table } 
( list ( 



Default: CPRI=S (this default value is supplied at execution time). 

Format: CPRI=S 

Notes: Do not specify either R or E. CPRI=S specifies that sending has priority 

over receiving, and must be specified when the line group supports time-sharing 

terminals. See additional notes at the description of the CPRI= operand of the 

Hne group DCB macro. 



Alternate Source: PP, OE, DD. 

Function: Specifies the translation table for this line group. 
Default: None. Either table or list must be specified. 

Format: Additional values that may be specified for table are EB41 (2741 EBCD 
transmission code), BC41 (2741 BCD transmission code), and CR41 (2741 
Correspondence code), list may be replaced by the symbolic name of a 
TRANLIST macro (described later). 

Notes: For a full description of the TRANS=table operand, see the corresponding 
entry in the line group DCB discussion in the section Defining the MCP Data 
Sets ). The TCAM code 105F (described in the same section) specifies the transla- 
tion table that translates all lowercase characters into uppercase for data entered 
by the IBM 1050 terminal. If the user specifies this code, his resulting data will 
not have any lowercase characters in it. 



STARTMH Macro Instruction 



The TRANS =Ust operand specifies that this Une group contains terminals for 
which determination of the transmission code is desired during execution. 

See additional notes at the description of the TRANS = operand of the line group 
DCB macro. 



See TSO Message Handler Macro Instructions . 



TSO Macro Instructions 



TSINPUT Macro Instruction 



Two macro instructions are provided for TSO support, TSINPUT and 
TRANLIST 



The TSINPUT macro 

• generates a queue control block for the time-sharing subtask, 

• generates an extension of the address vector table for time-sharing support. 



Name 


Operation 


Operand 


[symbol] 


TSINPUT 


(no operands) 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

This macro is required when the ENVIRON = operand of the INTRO macro 



i 
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TRANLIST Macro Instruction 



symbol 



LIST=(Uable /,.. ) 
(username) 



specifies either TSO or MIXED and is considered an error when 
ENVIRON=TCAM is coded. Only one TSINPUT macro may be specified, and it 
must be coded after the terminal table; it must be coded before the MH section of 
code. 



The TRANLIST macro 

• provides a list of translation tables so that messages entered at a terminal may 
be translated dynamically, 

• allows the programmer to specify more than one translation table for a line 
group. 

Any combination of TCAM-provided and user-provided tables may be specified 
by each TRANLIST macro. Multiple TRANLIST macros may be specified, and 
they must not be coded either before the INTRO macro or within the terminal 
table; they must be coded before the MH section of code. 



Name 


Operation 


Operand 


symbol 


TRANLIST 


(LIST=(aable >,...) ) 
1 cusername ) f 

(L2741 = (i table ),...) ,L1050=( Uable ),...) 
f usernamef < username ) 

,CHARS= (control chars,...) 

,OPFLD=opfldname 



Function: Name of the macro. 

Default: None. Specification of a name is required. 

Format: Must conform to the rules for assembler language symbols (see thee 

symbol entry in the Glossary ). 



Function: Provides translation for a line group consisting of either IBM 2741 or 
1050 terminals (but not both). 

Default: None. This operand must be specified for a line group consisting solely 
of either IBM 2741 or 1050 terminals. 

Format: table is replaced by one or more four-character codes indicating TCAM- 
provided translation tables (see the discussion of the TRANS = operand of the line 
group DCB macro in this appendix and in the section Defining the MCP Data 
Sets). 

username must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ) and represents one or more names of user-provided 
translation tables. 

Notes: This operand requires that the TERM= operand of the TERMINAL 
macro specify some value other than 5041. 
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L2741= 



( \ table I v.. ) 
c username ) 



,L1050:==(Uable 

I username 



Function: Provides translation for a line group whose TERMINAL macros specify 

some combination of IBM 2741 and 1050 terminals. 

Default: None. This operand must be specified for a TSO line group consisting of 

IBM 2741 and 1050 terminals. 

Format: table is replaced by one or more four-character codes indicating TCAM- 

provided translation tables (see the discussion of the TRANS = operand of the line 

group DCB macro in this appendix and in the section Defining the MCP Data 

Sets . 

username must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ) and represents one or more names of user-provided 

translation tables. 

Notes: The 1.21 Al- and L1050= operands must indicate the appropriate table or 

username for each IBM 2741 and IBM 1050. This operand requires that the 

TERM= operand of the TERMINAL macro specify 5041. 



CHARS=(control chars,...) 



Function: Specifies control character groups used by the CODE macro routine for 
determining dynamically the appropriate translation table to be used. 
Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 
symbol entry in the Glossary ). 

Maximum: As many as 5 control character groups, each consisting of no more 
than 8 characters. 

Notes: Any one of the control character groups specified by this operand may be 
specified also at the beginning of the first message for a time-sharing session. The 
characters specified as control characters should have unique hexadecimal repre- 
sentations in the translation tables specified. Where the control group is translat- 
ed the same for two tables, the first correct table found in the LIST=, L2741 =, or 
L1050= operand is used. 



OPFLD^opHdname 

Function: Permits TCAM to locate the option field containing the address of the 

translation table to be used. 

Default: None. This operand must be specified. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 

Notes: opfldname is indentical to the name specified for the OPTION macro 

whose option field is to contain the address of the translation table to be used. 

TSO Message-Handler Macro Instructions 

A Message Control Program consists of the Message Handlers, the sets of routines 
that determine the operations upon messages being received from or sent to 
remote stations or appUcation programs. A Message Handler is defined by a 
sequence of TCAM macro instructions and is constructed to handle messages for 
a particular line group, or for several line groups having similar characteristics. 

A Message Handler defines the macro-introduced routines that: 

• examine and process control information in message headers, and 

• perform functions necessary to prepare message segments for forwarding to 
their destinations, which may be stations, appUcation programs, or TSO. 



{ 
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STARTMH Macro Instruction 



The STARTMH macro defines the beginning of a message-handling routine for 
time sharing as it does for TCAM. The TSOMH= operand is added to the 
STARTMH macro for time-sharing support. The ALTMH= operand is added to 
the STARTMH macro for specifying an alternate Message Handler in a mixed 
environment. 



Name 


Operation 


Operand 


mhname 


STARTMH 


[,TSOMH=/ YES\ ][,ALTMH=mhname] 
(NO / 



TSO!VlH= 



j YES ) 
\ NO \ 



Function: Determines whether this MH is dedicated to handling time-sharing 

messages. 

Default: TSOMH=NO 

Format: TSOMH=YES or TSOMH=NO 

Notes: YES indicates that the following operands of STARTMH are appropriate: 

LC=IN 

STOP=YES 

CONV=YES 

If one or more of these operands are omitted, or if inappropriate values are 
specified, the system assumes the values listed here. 

NO indicates that this MH is not dedicated to handling time-sharing messages. 



A LTM H = mhname 



Function: Specifies the name of an alternate MH. 
Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols and must be 
the same as the name in the name field of the STARTMH macro for the alternate 
MH. 

Notes: This operand specifies the name of the TSO MH to receive messages from 
a terminal user logged on to time-sharing from a TCAM MH, or specifies the 
name of the TCAM MH to receive messages from a terminal user logged on to 
TCAM from a TSO MH. This operand is restricted to use in a mixed environ- 
ment. It requires that the alternate MH as well as this MH have a LOGON macro 
in its INHDR sequence. 



ATTEN Macro Instruction 



The ATTEN macro 

• causes the TSO/TCAM attention processing routine to receive control when 
hardware or simulated attention occurs; 

• is restricted to use in a TSO MH. 



Name 


Operation 


Operand 




ATTEN 


(no operands) 



This TSO macro instruction must follow either an INMSG or an OUTMSG 
delimiter macro instruction and must precede all MSGGEN macro instructions. 
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CARRIAGE Macro Instruction 



HANGUP Macro Instruction 



LOGON Macro Instruction 



The ATTEN macro requires that the TSOMH= operand of STARTMH specify 
YES. A name is not required and there are no operands. 



The CARRIAGE macro causes a TSO/TCAM routine to 



keep track of the position of the carriage; 
is restricted to use in a TSO MH. 



Name 


Operation 


Operand 




CARRIAGE 


(no operands) 



The CARRIAGE macro causes a TSO/TCAM routine to keep track of the 
position of the carriage by adding one to a one-byte count for each character that 
moves the carriage one position to the right, and subtracting one from the one- 
byte count for each character that moves the carriage one position to the left. 
When either a CR on an NL control character is encountered in the middle of a 
message, the count is reset to zero and counting is resumed. If an input line does 
not end with CR or NL, the carriage position count will not be zero. This TSO 
macro instruction, must follow an INBUF delimiter macro instruction, and it 
requires that the TSOMH= operand of the STARTMH macro specify YES. A 
name is not required and there are no operands. 



The HANGtJP macro 

• calls a TSO/TCAM routine to be executed at end-of -message to test for I/O 
errors and error bits in the message error record; 

• handles hardware errors that occur at the user's terminal; 

• is restricted to use in a TSO MH. 



Name 


Operation 


Operand 




HANGUP 


(no operands) 



This TSO macro instruction must follow either an INMSG or an OUTMSG 
delimiter macro instruction and must precede all MSGGEN macros; it also 
requires that the TSOMH= operand of STARTMH specify YES. A name is not 
required and there are no operands. 



The LOGON macro 



invokes a TSO/TCAM routine to perform logon procedures; 

must be used in all TSO Message Handlers or any TCAM Message Handler 

operating in a mixed environment; 

should be coded immediately following the CODE macro in the inheader 

subgroup (or inblock for LMD terminals) of the TSO or TCAM Message 

Handler unless an INBLOCK macro exists in the TCAM MH. The CODE and 

LOGON macros should then follow the INBLOCK macro and precede the 

INHDR macro; 

only one LOGON macro is allowed per Message Handler. 



i 
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The LOGON format is: 



Name 


Operation 


Operand 




LOGON 


(no operands) 



SIMATTN Macro Instruction 



The TSO/TCAM routine scans for the EBCDIC characters LOGON or 
TCAMON in the first buffer of every message destined for a TSO MH or TCAM 
MH operating in a mixed environment. The LOGON macro must be specified in 
the inheader subgroup of the appropriate MH. A name is not required and there 
are no operands. 

Note: The EBCDIC characters LOGON and TCAMON are recognized as 
commands by the TSO/TCAM routine. Do not confuse the LOGON com- 
mand with the LOGON macro. 



The SIMATTN macro 

• gives control to a routine to handle a simulated attention string or code; 

• is restricted to use in a TSO MH. 



Name 


Operation 


Operand 




SIMATTN 


(no operands) 



The SIMATTN routines scans the initial bytes in the first input buffer of a mes- 
sage for a simulated attention string or code; if found, this routine processes the 
simulated attention request. This macro must follow an INBUF delimiter macro 
and requires that the TSOMH= operand of STARTMH specify YES. A name is 
not required and there are no operands. 

Message-Handler Routine 

The TSO MH routine is a sequence of macro instructions that perform the 
message-handling functions required for TSO. The LOGON macro causes 
messages to be routed to the time-sharing input destination. The STARTMH 
macro defines the beginning of a Message Handler routine. A more detailed 
discussion of the TSO operand that has been added to the STARTMH macro can 
be found in the section TSO Message Handler Macro Instructions in this 
appendix. 

STARTMH-Dependent TSO Macro Instructions 

These macro instructions may be included only in an MH whose STARTMH 
delimiter macro instruction specifies TSOMH=YES: 

• ATTEN 

• CARRIAGE 
. HANGUP 

. SIMATTN 

These TSO macro instructions are discussed in an earlier section of this appendix, 
TSO Message Handler Macro Instructions. 

Non-Restricted TCAM and TSO Macro Instructions 

The following macros may be used without restriction in a TSO MH. Macros that 
are designated (TSO) are discussed in greater detail in TSO Message Handler 
Macro Instructions in this appendix. Those designated (TCAM) are discussed in 
earlier sections of this programmer's guide. 
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• ATTEN (TSO) causes the attention processing routine to receive control when 
a hardware or simulated attention occurs. 

• CANCELMG (TCAM) causes cancelation of a message if a specified error 
occurs. 

• CARRIAGE (TSO) keeps various carriage position and print line counts. 

• CODE (TCAM) provides translation functions. If dynamic translation is 
desired, this macro is required and operands must not be specified. If transla- 
tion need not be dynamic, there are no restrictions on the use of this macro's 
operands. For TCAM buffers, translation is performed on a message-by- 
message basis. Once a user logs on for a time-sharing session, the same trans- 
mission code is used until he logs off. One of the following return codes is 
passed in register 15 after CODE executes: 

Code Meaning 

Message translated 

4 Correct translation table could not be found. Message not translated. 

• COUNTER (TCAM) keeps a count of incoming or outgoing message segments 
orcomplete messages depending on the subgroup in which the macro is issued. 

• CUTOFF (TCAM) checks for incoming TCAM buffers filled with identical 
characters (indicating terminal malfunction). In such a case, bit 7 is set in the 
message error record and reception is terminated. The CUTOFF macro also 
specifies the maximum number of characters allowed in either a TCAM or a 
TSO message; if the maximum is exceeded, reception is terminated and bit 7 is 
set in the message error record. Note that only specifying the maximum 
number of characters is utilized for time-sharing support. 

• HANGUP (TSO) causes a TSO/TCAM error processing routine to receive 
control to test for and handle hardware error conditions at the user's terminal. 

• LOCOPT (TCAM) provides access to the option field of the terminal table, 
permitting examination and modification of the contents of the fields. 

• LOGON (TSO) invokes a TSO/TCAM routine to perform logon procedures. 

• MSGGEN (TCAM) generates a special response message and routes it immedi- 
ately to either the originating or the destination station. The response message 
bypasses normal message handling, queuing, logging, and buffering functions. 

• MSGLIMIT (TCAM) limits the number of messages to or from a station during 
a single transmission sequence. 

• SIMATTN (TSO) gives a routine control to handle simulated attention process- 
ing for input messages. 

• TERRSET (TCAM) causes bit 20 to be set in the message error record to 
indicate, at the discretion of the user, that a user-defined logical error occurred. 

Operand-Restricted TCAM Macro Instructions 

The following TCAM macro instructions may be used in a TSO MH with the 
indicated operands only. 



LOG Macro Instruction 



The LOG macro places copies of messages or message segments on a sequential 
medium such as magnetic tape. 



Name 


Operation 


Operand 


[symbol] 


LOG 


dcbname 
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symbol 



dcbname 



PATH Macro Instruction 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the name of the data control block for logging. 

Default: None. This operand must be specified. 

Format: Identical to the name of the data control block specified for the message 

log data set. 

Notes: If dcbname does not match the name of a valid data control block, the 

LOG macro does not execute, and a return code of X'04' is set in the low-order 

byte of register 15. 

The LOG macro may be coded in the inheader, inbuffer, outheader, or outbuffer 
subgroups. 



The PATH macro sets a bit in the option field specified by the opfield operand. 
Succeeding macros may be executed conditionally, depending upon the bit set. 



Name 


Operation 


Operand 


[symbol] 


PATH 


switch,opfield 



symbol 



switch 



opfield 



Function: Name of macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



Function: Specifies the path switch setting to be made for the byte residing in the 

option field named by the opfield operand. 

Default: None. This operand must be specified. 

Format: Decimal or hexadecimal. If hexadecimal format is specified, framing X* ' 

or XLT ' characters must be used. 

Maximum: 255 or a 1-byte hexadecimal field. 

Notes: If is specified, all eight path switches are turned off. If 255 (or XTF') is 

specified, all switches are turned on. 



Function: Specifies the path-switch byte to be operated upon. 

Default: None. This operand must be specified. 

Format: Identical to the name of a l-bjrte field in the option table that is defined 

by an OPTION macro. 

Notes: If the option field cannot be found, the path-switch byte is not operated 

upon, and a return code of X*00' is set in the low-order byte of register 15. See 

additional notes at the description of the opfield operand of the PATH macro. 

TCAM Macro Instructions Not Used 

The following macro instructions may not be used in a TSO MH (they do not 
assemble and MNOTEs are generated). 
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CHECKPT 

DATETIME 

ERRORMSG 

FORWARD 

HOLD 

INITIATE 

LOCK 

MSGEDIT 

MSGFORM 

MSGTYPE 

ORIGIN 

PRIORITY 

REDIRECT 

SCREEN 

SEQUENCE 

SETEOF 

SETSCAN 

UNLOCK 

TSO/TCAM Mixed Environment 

Mixed-environment support will allow non-dedicated terminals, switched or 
nonswitched, to be used with either TCAM applications or TSO applications. The 
user will also have the option of dedicating terminals to TSO or TCAM applica- 
tions. A user with a non-dedicated terminal may switch back and forth between 
TCAM and TSO appUcations by entering a LOGON command if in a TCAM 
session or a LOGOFF followed by a TCAMON if in a TSO session. 

Defining Terminals for Message Handlers 

Dedicated terminals may be defined by the keyword values (TS, DR, DN, MO, 
MR, MN) of the QUEUES = operand of the TERMINAL macro. Non-dedicated 
terminals may be defined by the keyword values (DRT, DNT, MOT, MRT, MNT) 
of the QUEUES= operand of the TERMINAL macro. Non-dedicated terminals 
can only be the time-sharing supported types. All dedicated and non-dedicated 
terminals will be assigned to either a TCAM or a TSO Message Handler (MH). A 
non-dedicated terminal should be assigned to the MH defining the type of applica- 
tion (TSO or TCAM) most frequently used by that terminal. This assignment is 
made by coding the DCB= operand of the TERMINAL macro to point to a DCB 
whose MH= operand points to a TSO MH or a TCAM MH. 

Defining Message Handlers to Allow Multiple Applications 

A TCAM MH assigned non-dedicated terminals should specify the alternate TSO 
MH to be used for TSO appUcations in the ALTMH= operand of its STARTMH 
macro. Conversely, a TSO MH assigned non-dedicated terminals should specify 
the alternate MH to be used for TCAM appUcations in the ALTMH= operand of 
its STARTMH macro. 

TSO/TCAM Mixed Environment Functional Flow 

Dedicated terminals are functionally unchanged. The rest of this discussion 
applies to non-dedicated terminals that may be connected to switched or non- 
switched Unes. When a user begins a terminal operation, the terminal wiU be 
logicaUy connected to the MH to which it was initially assigned. Terminal trans- 
missions wiU proceed normally through the assigned MH untU a LOGON or 
TCAMON command is received by that MH. The command wiU identify the f 

user's request for a specific function. If the request is for the type of application 
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to which the MH is already connected, no switch is made. If not, the alternate 
MH specified by the MH STARTMH macro will be checked; if this alternate MH 
supports the requested function, a switch will be made to route all subsequent 
traffic to this alternate MH. If the alternate MH does not support the requested 
function, no switch will be made. If a switch is attempted to a TSO MH when 
TSO is not active, no switch will be made. The following examples summarize 
mixed-environment functional flow: 

1. A LOGON command from a terminal assigned to a TCAM MH that specifies 
an alternate TSO MH in its STARTMH macro will cause the terminal to be 
temporarily switched to TSO and will cause subsequent message traffic to be 
routed to the alternate TSO MH. When a LOGOFF command or terminal 
disconnection is recognized, the terminal is switched back to its assigned 
TCAM MH. At that time any messages that have been queued for that termi- 
nal can be received by entering TCAMON at the terminal and switching a 
message to itself. 

2. A TCAMON command from a terminal assigned to a TSO MH that specifies an 
alternate TCAM MH in its STARTMH macro will switch the terminal tempo- 
rarily to TCAM and will cause subsequent message traffic to be routed to the 
alternate TCAM MH, When a LOGON command is recognized, the terminal 
is switched back to its assigned TSO MH. 



Note: Initiate mode messages from non-dedicated terminals assigned to a 
TSO MH are not supported. If TCAM messages are queued for a terminal 
while that terminal is in a TSO session the queued messages can be received 
after a hangup or LOGOFF by entering TCAMON and switching a TCAM 
message to the terminal. The message switch can be accomplished by coding 
the following TCAM macros in the inheader subgroup of the MH that is to 
process the TCAM messages from this terminal: 



SETSCAN TCAMON, BLANK=NO, MOVE=RETURN 

test return code from SETSCAN for TCAMON found; 
if TCAMON not found continue INHDR processing. 

FORWARD DEST=ORIGIN 

(forward TCAMON to ORIGIN) test return code from 
FOWARD; if foward is successful execute the inbuffer 
subgroup. 



Operator Control Considerations 

Discussions of the following operator commands are extensions of discussions of 
the same commands in an earlier section of this publication, Operator Commands . 
The functions and formats of commands are repeated here, and responses peculiar 
to TSO follow the illustrated format of each command. An explanation of each 
response appears after the response. See Operator Control in the section Using 
TCAM Service Facilities for a complete explanation of each command as it is 
used in TCAM. 

ACTVATED 

This command requests a list of all entries in the invitation Ust for the specified 
lines that are currently active for entering messages. 
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INTERVAL 



QSTATUS 



Format: 








control characters 


operation 


operand 


control chars 


J DISPLAY) 

^D \ 


TP,ACT, 


jgrpname,rlni 
(address S 



Response: 

IED036I (grpname,rln 
{address 



> ACTIVE=J 



statname 
NONE 



[ (userid) 



Explanation: 

userid is added to this response to indicate that the terminal named by statname 
was engaged in a time-sharing session when this command was entered, where 
userid is identical to the value specified by the TSO terminal user during his logon 
procedure. Each statname entry in the response that represents a terminal en- 
gaged in a time-sharing session is followed immediately by the appropriate userid 
entry. The user identification is enclosed in parentheses; if less than eight charac- 
ters, it is padded to the right with blanks. 



This command activates the system interval whose value is specified by the 
INTVAL= operand of the INTRO macro. 

Format: 



control characters 


operation 


operand 


control chars 


1 MODIFY f 


j[procname.]id^ 
cjobname > 

,INTERVAL=SYSTEM 



Response: 

IED047I SYSTEM INTERVAL CANNOT BE ACTIVATED 

Explanation: 

The TSO/TCAM system did not permit this command to execute because TSO 
was active in the system. This command is effective for starting the system 
interval any time before starting TSO, or after TSO has been stopped, but not 
while TSO is active. 



This command requests display of the fields of a queue control block containing 
the number of messages queued, the queue status, and the priority levels permitted 
for either a line or a station queue. 



{ 
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Format: 



STOPLINE 



control characters 


operation 


operand 


control chars 


J DISPLAY^ 


TP,QUEUE,statname 



Response: 

IED031I statname QUEUE SIZE=number ,QUEUETYP=type , 
STATUS=status, . . . , PRIORITY=integer , . . . 

Explanation: 

A response of NO in the QUEUETYP= field of the response indicates 

that this command was entered where statname was replaced 

by the name of a TERMINAL macro that is associated with a TSO line group. 



This command stops transmission of messages on a line or a line group. 

The last operand determines whether transmission stops at the end of the current 

message or immediately. 



Format: 








control characters 


operation 


operand 


control chars 


J VARY) 

\W S 


((grpname,rln)) 
j(grpname,) \ 
'address ^ 


,0FFIP, \c| 



Response: 

IED0121I TSO SESSION ON LINECgrpname , rlnJCOMMAND REJECTED 

c address > 
Explanation: 

This command was entered to stop transmission on a line or line group where the 
line (or a line in the line group) was currently engaged in a time-sharing session. 
Re-enter this command when the line is not engaged in a time-sharing session, or 
when no line in the line group is engaged in a time-sharing session. 

Response: 

IED026I grpname ALL STOPPED 

Explanation: 

A form of the command was entered to stop transmission on all the lines in the 
specified line group. All lines that were not currently engaged in a time-sharing 
session were stopped as requested; any lines engaged in a time-sharing session 
were not stopped, even though response message IED026I was returned. Re- 
enter this command when the line, or lines, are not engaged in a time-sharing 
session. 



SYSCLOSE 



This command initiates either a quick or a flush closedown of a TCAM system. 
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Format: 



control characters 


operation 


operand 


control chars 


r"} 


TP,| quick) 

(flush/ 



Response: 

IED01 21 TSO, SESSION ON LINE HALT COMMAND REJECTED 

Explanation: 

The TSO/TCAM system did not permit this command to execute because TSO 
was active in the system. This command is effective for deactivating the 
TSO/TCAM system any time before starting TSO, or after TSO is stopped, but 
not while TSO is active. 



Checkpoint /Restart Considerations 

The checkpoint/restart facility cannot be used for foreground tasks. Consequent- 
ly, checkpoints for swappable application programs are ignored, and apphcation 
programs must be reinitiated by the user. 

The status of a time-sharing session is not checkpointed; therefore, system failure 
in the middle of a time-sharing session causes all message traffic to be lost for the 
terminal. The status of each line in the TSO line group is checkpointed, however, 
and the condition of the line at restart time is the same as before closedown or 
failure (for instance, if a line at failure was enabled, it is enabled at restart time). 
Once the system restarts, a TSO terminal user must repeat his logon procedures 
and restart his session. 



Swappable Application Programs 

See the TSO Guide for including TCAM swappable application programs in the 
foreground. 

Closing TCAM 

If TSO is still active when an MCPCLOSE macro is issued in a TCAM application 
program, closedown is unsuccessful and a return code of X'04' is set in register 
15. In order for closedown of the TCAM MCP to be successful, close TSO and 
reissue the MCPCLOSE Macro in an application program. 

TSO Bits in the Message Error Record 

This section is an extension of Appendix B: Message Error Record ; it identifies 
and describes TSO bits that may be set in the message error record during a 
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time-sharing session in a mixed environment. 
Bit Meaning 

Invalid logon 

The LOGON routine detected a misspelled or otherwise invalid LOGON 
message. 

1 Logon failure 

An attempt to log on to the TSO system failed due to an invalid com- 
mand. 

2 Non-TSO terminal 

The terminal attempting to log on is not supported as a TSO terminal. 

3 TSO not active 

A terminal is attempting to log on, but TSO is not active in the system. 

4 Too many TSO users 

A terminal is attempting to log on, but the maximum number of TSO 
users are already logged on. 

10 Dynamic translation error 

An error occurred while attempting to determine the correct translation 
table for the terminal logging on. 

1 1 Automatic line number 

Automatic Une numbering is requested for this TSO terminal. 

1 6 Attention-input ignored 

An input attention occurred, and the current input message consequently 
was ignored. 

17 Attentions-input deleted 

An input attention occurred, and the current message consequently was 
deleted. 

19 Simulated attention 

The simulated attention routine detected a request for a simulated atten- 
tion. 

22 Attention 

An attention request was detected. 

TSO/TCAM 3270 Device-Dependent Considerations 

TSO/TCAM provides support for: 

3271 Remote Control Units 

3272 Local Control Units 

3277 Clustered Displays 48C and 19C 

3275 Remote Stand-alone Displays 48SR and 19SR 

The 3271 Remote Control Units are supported in a multipoint configuration. 



Input 



An input line to TSO is defined as all modified data fields between the Set Buffer 
Address (SBA), the start of the input message, and the end of the message. The 
NEW LINE key repositions the cursor only and has no effect on the buffer 
contents. Thus, all input from one transmission will be treated as one line or a 
multiple thereof. A Null Line to TSO is defined as input from the ENTER key 
only. Function key substitution for the ENTER key will be considered Null Line 
input. 



Input Data Stream 



TSO/TCAM will provide additional control character removal for input from the 
Ij 3270 device in a TSO session. Upon completion of all input editing, the 3270 

^ local and remote input messages will be of the same format. 
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Remote Input 



The TGET EDIT and TGET ASIS interfaces are supported as specified in the 
Supervisor and Data Management Macro Instructions publication. In EDIT 
mode, all terminal control characters are suppressed from the data. In ASIS mode, 
all terminal control characters remain in the data. 



The remote input data stream format is: 



TSO 

editing 
removed 



Not Moved to 
TSO user buffer 
in EDIT mode 



Operator 
supplied 



TSO editing 
removed 




A C C S A A 

I U U B D D 

R A 

2 



D 



Unformatted screen 



D D 
1 2 



(before Logon) 
Formatted screen 



.Text. 



E 
T 
X 



Where: 

STX 

CU 

DVC 

AID 

CURn 

CUR2) 

SBA 

ADDRl 

ADDR2 

ETX 



is the start-of-text, line-control character. 

is the control unit fixed-return address. 

is the device fixed-return address. 

is the attention ID. * 

is the two-character address of the cursor position. 

is the set buffer address order code. 

is the two-character address of the beginning of text. 

is the end-of-text, line-control character. 



Local Input 



*The input AID byte (EDIT OR ASIS mode) is preserved in the device dependent 
field immediately following the option fields of the terminal table. Also present 
are the display screen size (rows and columns) bytes. 



The local input data stream format is: 



Not moved to TSO user 
buffer in EDIT mode 



A C C S A A 

I U U B D D 

D R R A D D 

12 12 



Operator supplied 

.TEXT. 



Unformatted 

buffer 

{ before Logon ) 

Formatted buffer 



i 
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Output Data Stream 



TSO/TCAM will provide additional control character editing facilities for output 
to the 3270 device in a TSO session. The TPUT EDIT, ASIS, and control mode 
interfaces will be supported as specified in Supervisor and Data Management 
Macro Instructions . In EDIT mode, all the necessary terminal control characters 
will be inserted into the data. In ASIS mode, all the necessary terminal control 
characters (ESC, CMD, WCC, and SBA/CUR1/CUR2) will be inserted if not 
suppUed or correctly defined in data. In control mode, valid terminal control 
characters will be allowed or generated in the data. A bypass or restore character 
in the output data, or a new-line character at the end of an ASIS message will be 
converted to an appropriate attribute byte or insert cursor order. 



Remote Output 



The remote output data stream format after TSO editing is: 



TSO 

editing TSO edit mode supplied 



s 

T 
X 



Where: 

STX 

ESC 

CMD 

WCC 

SBA 

CURll 

CUR2/ 

SF 

ATTl 

ATT2 

CUR31 

CUR4/ 

INC 

ETX 



ECWSCCSA 
SMCBUUFT 
C D C A R R T 

^^ J 2^ ^ 

TSO control 
mode supplied 
and TSO ASIS 
mode inserted/ 
corrected 



is the start-of-test, Une-control character (X'02'). 

is the escape control character (X'27'). 

is the command operator (XTT - write). 

is the write control character (X'Cl'). 

is the set buffer address order code (X'l T). 

is the two-buffer address. 

is the start field order code (X*1D'). 
is the write attribute byte (X'C8'). 
is the read attribute byte (X'40'). 
is the two-buffer address. 

is the insert cursor order code (X'13'). 

is the end-of-test, line-control character (X'03'). 



User TSO edit mode TSO 

supplied supplied editing 

. .text. . S A S C C I E 

F T B U U N T 

T A R R C X 

2 3 4 



Local Output 



The local output data stream format after TSO editing is: 



TSO edit mode 
supplied 



User supplied 



TSO edit mode 
supplied 



W S C C S A 

C B U U F T 

C A R R T 

1 2 1 

TSO control 
mode supplied 
and TSO ASIS 
mode inserted/ 
corrected 



.text. 



S A S C C I 

F T B U U N 

T A R R C 

2 3 4 
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Screen Format 

Each output message will have a high-intensity, attribute byte as its first position 
(X'C8') and a default attribute byte as its last character position (X'40*). A 
default attribute byte will be written in the right-most position of the last Une of 
each input message overwriting any display character occupying that position. 
Normal screen format, therefore, will show the output data indented one position 
and of higher intensity than the input data. The 3277 display is formatted with a 
default attribute byte (X'40') located at the last buffer position (479 or 1919) 
upon initial LOGON and subsequent TSO or CLEAR-key initiated screen era- 
sures. In EDIT mode, the output after input will be on the next physical line of 
the screen. Input after output will always begin at the cursor position. The user 
may control screen format by using TPUT ASIS and including the necessary 
control characters, commands, attribute bytes, and set buffer-address, character 
sequences in the output data stream. 



i 
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Concentrating and Deconcentrating Messages 

When incoming messages from a group of terminals are directed to a remote 
device that combines (concentrates) them into a single physical message for 
forwarding to the CPU, TCAM extracts the messages and directs them to their 
appropriate incoming Message Handlers. Conversely, if a TCAM Message 
Handler concentrates outgoing messages into a single physical transmission and 
directs them to a remote message-deconcentrating device, the device selectively 
forwards the various messages within the physical transmission to their appropri- 
ate destinations. A concentrator, therefore, is any remote device that concen- 
trates incoming messages and deconcentrates outgoing messages in a TCAM 
network. 

This concentration/deconcentration process increases line availability and reduces 
the amount of CPU time required for handUng lines. This appendix describes 
TCAM*s role in accepting and deconcentrating input from a concentrator, and in 
building and transmitting concentrated output messages to be directed to a 
concentrator. The reader should first be familiar with the procedures for extract- 
ing logical messages from data in an incoming transmission sequence (deblocking) 
described in Handling Logical Messages in the chapter Designing the Message 
Handler . 



Defining the Network 



The description of the TERMINAL macro instruction, in the section Defining 
Terminal and Line Control Areas , should be read and understood before reading 
this section. The following discussion and examples expand on the earlier descrip- 
tion, (i 

When defining a TCAM network to handle concentrated messages, a TERMINAL 
macro instruction is coded to define a remote message-concentrating device and, 
immediately following that macro, TERMINAL macro instructions are coded for 
the terminals attached to that device. If two or more message-concentrating 
devices are defined on a multipoint Une, the TERMINAL macro for the second 
message-concentrating device on the line must immediately follow the 
TERMINAL macro defining the last station attached to the first concentrator 
device on the line. Other concentrators on the same line and their attached 
terminals must be defined in the same manner beginning immediately after the 
TERMINAL macro for the last terminal attached to the second concentrator. 
Further, message-concentrating devices on a multipoint Une must be specified 
before other devices, and switched message-concentrating devices may not be 
specified. 



{ 
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DVCID= 



Example: 

Concentrators and non-concentrators on a multipoint line 



DVCID=C0NC,DCB=DCB1 ,RLN=1 
DVCID=A,DCB=DCB1 ,RLN=1 , . . 
DVCID=B,DCB=DCB1 ,RLN=1 , . . 
DVCID=C0NC,DCB=DCB1 ,RLN=1 
DVCID=C,DCB=DCB1 ,RLN=1 , . . 
DVCID=D,DCB=DCB1 ,RLN=1 , . . 
DVCID=C0NC,DCB=DCB1 ,RLN=1 



C0NC1 


TERMINAL 


T1 


TERMINAL 


T2 


TERMINAL 


C0NC2 


TERMINAL 


T3 


TERMINAL 


T4 


TERMINAL 


C0NC3 


TERMINAL 



NOTCONC TERMINAL DCB=DCB1 ,RLN=1 , . . . 

Two operands of the TERMINAL macro, DVCID= and QCNTRL=, are used 
primarily to specify the characteristics of devices handhng concentrated-messages. 
DVCID= indicates whether the TERMINAL macro is for a concentrator or an 
attached terminal. QCNTRL= controls queuing and line scheduling for data 
going to terminals attached to a concentrator. Each use of the QCNTRL= 
operand results in a destination queue. The user may group attached terminals to 
share a common destination queue, or he may specify a separate destination queue 
for each attached terminal. 



Name 


Operation 


Operand 


symbol 


TERMINAL 


[,DVCID= ^(CONC[,integer])n 
I chars / 

(none ) 
[,qcntrl=( (all ) 

)(MSG[, Usgcount(] \ 

) \- M 

(^bytecount / 
[,L][,STATUS][,char])][,CTBMAX=integer] 



Function: Identifies the terminal table entry as being for a concentrator 
or a terminal attached to a concentrator. 

Default: None. If the device associated with this TERMINAL macro is a concen- 
trator or is attached to a concentrator, this operand is required. 
Format: (CONC, integer), chars, or NONE. 

Notes: (CONC, integer ) specifies that this is a concentrator, integer , if coded, 
specifies the number of bytes in the longest ID for a terminal attached to the 
concentrator and may be from 1 to 8 inclusive. If integer is omitted, a one-byte 
ID is assumed for all attached terminals. 



chars specifies the ID of a terminal attached to a concentrator and must be in 
unframed hexadecimal format. The ID is inserted at the beginning of each CTB 
destined for this terminal (assuming that the CTBFORM macro specifies 
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QCNTRL=: 



DVCID==YES). Do not specify FF. ID insertion occurs at CTBFORM execution 
time, thus any subsequent CODE macros will cause the ID to be translated. 

NONE specifies that this is a terminal attached to a concentrator, but has no ID. 
ID insertion does not take place for messages destined for this terminal. 



Function: Controls dequeuing of messages destined for a concentrator. 
Default: None. This operand is required for the first terminal on a concentrator 
and is optional for all other terminals. Use of the QCNTRL= operand requires 
that TERMINAL also specify the QUEUES= operand. If QNTRL= is not 
specified, do not specify the QUEUES = operand. 

Format: msgcount , if coded, may be any decimal integer between 1 and 255, 
inclusive; if MSG is coded but msgcount is omitted, a value of 1 is assumed for 
msgcount . bytecount if coded, may be any decimal integer between 1 and 32,767. 
Notes: Absence of this operand causes this terminal to share the queue control 
block of the first preceding TERMINAL macro that does include the QCNTRL= 
operand. Thus, several terminals may be grouped under one queue control block. 
Queuing is discussed further in Queuing Techniques for Terminals Attached to 
a Concentrator in this appendix. 

ALL specifies that all messages in this queue are sent in one transmission. Each 
message is handled individually through the MH and treated as a CTB in the 
concentrated message; that is, the ID is inserted at the beginning of each message 
and the delimiter at the end, unless overridden by the CTBFORM macro. ALL 
does not permit execution of the outmessage subgroup for messages read from the 
associated destination queues (except that outmessage execution is permitted if 
there is an initial selection error or if transmission of outgoing messages is unsuc- 
cessful due to a lack of buffers), and TCAM considers the messages to be sent 
immediately after reading them. If All is specified, status analysis may not be 
performed (that is, do not code STATUS as the third suboperand). 

(MSG[, msgcount ]) specifies the number of messages to be sent from this queue. 
If only MSG is specified, one message is sent. MSG or (MSG,1) must be specified 
in order to code STATUS as the second sub-operand. If a value other than MSG 
or (MSG,1) is specified, then the outmessage subgroup is not executed, and 
TCAM considers messages to be successfully sent after they are read from their 
destination queue, msgcount may be from 1 to 255, inclusive. 

bytecount specifies the maximum number of bytes that may be sent as a CTB (may 
be from 1 to 32767, inclusive). The number of bytes sent is determined either by 
reaching the number specified by bytecount or by reaching the end of a message, 
whichever occurs first. Data for a CTB is never taken from more than one 
message, but a single message may require multiple CTB transmissions. Sufficient 
data is read into buffers to obtain the amount specified by bytecount (including 
prefix and idle characters). These buffers are filled so that the amount read is 
greater than or equal to bytecount , but not exceeding end-of -message. After the 
data is processed through the MH, only the amount specified by bytecount 
(including prefix and idle characters) is sent; the next transmission begins with the 
first byte of data following the last byte sent. If STATUS is coded as the second 
suboperand, status analysis is performed on each CTB, where several CTBs may 
be required for a complete messages. 

All terminals attached to a concentrator using byte count queue control (i 

(QCNTRL=^(integer,....,)) must use the same buffer size. If the BUFSIZE= ^ 
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CONC 


TERMINAL 


TERM1 


TERMINAL 


TERM2 


TERMINAL 


TERMS 


TERMINAL 


TERM4 


TERMINAL 


TERM5 


TERMINAL 



operand is specified on any TERMINAL macro using this queuing technique, the 
BUFSIZE= operand must also be coded in the TERMINAL macro for the 
concentrator to which the terminal is attached, and the same buffer size must be 
specified. 

Example: 

DVCID=CONC,BUFSIZE-100, . . . 
DVCID-F 1 , QCNTRL= ( MSG ) , . . . 

DVCID=F2,QCNTRL=( 1 20 , , , 90 ) , . . . , BUFSIZE=1 00,. 
DVCID=F3,QCNTRL=(MSG, , ,90 ), . . . 

DVCID=F4,QCNTRL=( 50, , ,90 ), . . . , BUFSIZE-1 00 , .., 
DVCID=F5,QCNTRL=( 200, , ,90 ), . . . 

L specifies that priority levels are to be estabUshed for a group of terminals so that 
no more than one message for each of the terminals will be sent in a single trans- 
mission (queuing by priority level is discussed in Queuing Techniques for 
Terminals Attached to a Concentrator in this appendix). This suboperand 
requires that the first value specified in the QCNTRL= operand be either (MSG) 
or (MSG,1), and that this TERMINAL macro also specify the LEVEL= operand, 
where the number of priority levels equals the number of terminals to be con- 
trolled. If n priority levels are specified, then the next n terminal entries in the 
terminal table are part of this control group, and none of these next n entries may 
specify the QCNTRL= operand. The first entry following this control group (if 
another entry exists) should either specify the QCNTRL= operand, or specify 
another concentrator entry, or be for a device that is not a concentrator (and the 
QCNTRL= operand is not specified). The same queuing control may be ob- 
tained by specifying QCNTRL=MSG for each of the individual terminal entries in 
the terminal table. The advantage of specifying QCNTRL=(...,L,...) is that only 
one destination queue is generated instead of a destination queue per terminal, but 
use of the L suboperand requires a priority scheme to direct messages on the 
queue to their appropriate destinations. 

Example: 

Assume four attached terminals, A, B, C, and D, to be serviced from a single 
destination queue, and at most, one message per destination is to be dequeued for 
each transmission: 

A TERMINAL DVCID=id,QCNTRL=( MSG, L, . . . ),LEVEL=( 1,2,3),... 

B TERMINAL DVCID=id, . . . , LMD=YES 

C TERMINAL DVCID^id, . . . 

D TERMINAL DVCID=id, . . . 

STATUS specifies that status analysis is to be used in handling the queue generat- 
ed by this TERMINAL macro. This suboperand requires that MSG, (MSG,1), or 
bytecount be coded as the first value of the QCNTRL= operand. Once the 
user-specified amount of data is sent, execution of the out-message subgroup for 
this message is delayed and no more data is sent from the queue until a subsequent 
QACTION macro so specifies (the QACTION macro is discussed later in this 
appendix), and transmissions to the terminal are interrupted temporarily after 
each transmission from the queue. If STATUS is not specified, there is no delay 
in executing the outmessage subgroup, and the user-specified amount of data may 
be sent with each transmission (that is, the queue is free for sending if no other 
restraints exist, such as using the HOLD macro to intercept messages). The same 
MH must be used for all terminals using the same output queue. 

char specifies, in unframed hexadecimal format, from one to eight characters to 
delimit each CTB sent from the queue. This character is inserted into the data 
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stream after MH processing and is not translated. Therefore, the character must 
be the hexadecimal equivalent of the appropriate line control character used by 
the concentrator for deblocking. Do not specify FF . 



CTBMAX=integer 



Function: Specifies maximum number of CTBs to be sent to a concentrator in 

any transmission sequence. 

Default: None. Specification of this operand is optional. 

Format: CTBMAX= integer 

Maximum: 255 

Notes: This operand may be included in a TERMINAL macro for a concentrator, 

and is invaUd if the TERMINAL macro is for a terminal (the use of this operand 

requires that the same TERMINAL macro specify DVCID=CONC). The value 

for integer must be between 1 and 255 inclusive. 

Queuing Techniques for Terminals Attached to a Concentrator 

There are four queuing techniques that may be used for terminals attached to a 
message-concentrating device: 

• queuing by concentrator 

• queuing by priority level 

• queuing by groups 

• queuing by terminal 



Queuing by Concentrator 



When queuing by concentrator only, all attached terminals are serviced from a 
single destination queue. This method of queuing requires less main storage than 
queuing either by priority level, by groups, or by terminal. The following example 
defines a terminal network that uses queuing by concentrator. 

Queuing by Concentrator Only 



CONC 


TERMINAL 


DVCID=CONC,QBY=T, 


Tl 


TERMINAL 


DVCID=id,QCNTRL=, 


T2 


TERMINAL 


DVCID=id, . . . 


T3 


TERMINAL 


DVCID=id, . . . 


T4 


TERMINAL 


DVCID=id, . . . 



Queuing by Priority Level 



Queuing by Groups 



Queuing by priority level establishes a single destination queue for a group of 
terminals (see the discussion of the (L suboperand). This method of queuing 
requires less main storage than estabUshing a destination queue for each terminal 
in the group (that is, coding the QCNTRL= operand on each TERMINAL macro 
in the group results in using more main storage). 

When queuing by priority level, the user must code the LEVEL= operand on each 
TERMINAL macro that specifies QCNTRL=(...,L,...). TCAM sends a single 
message from each priority level established by the LEVEL= operand. This 
technique cannot be used if the user wishes to send partial messages or multiple 
messages from a single destination queue. 



As in queuing by priority level, queuing by groups estabUshes a destination queue 
for a group of terminals. Priority levels can be used with this queuing technique; 
however, TCAM determines, by the QCNTRL= operand, how much data to send 
from each destination queue in a single transmission. The priority levels are 
serviced the same as in normal TCAM queuing. That is, all messages are sent 
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progressively from the highest-existing priority level before any messages are sent 
from the next lower priority level. 

This technique provides the same queuing control as queuing by priority level by 
specifying QCNTRL=MSG for each of the individual terminal entries in the 
terminal group. However, more main storage is required since a destination queue 
is established for each QCNTRL=^ operand. 

Queuing by Groups (Terminals Tl, T3, and T4 constitute the first group, T2 the 
second group, and T5 the third group.) 

CONC TERMINAL DVCID=CONC, QBY=T 

DVCID=id, QCNTRL-,... 
DVCID=id, . . . 
DVCID=id, . . . 
DVCID=id,QCNTRL=, . . . 
DVCID=id,QCNTRL=, .*. . 

In this example, three destination queues are generated, one serving terminals Tl, 
T3, and T4, one serving T2, and the last serving T5. 



T1 


TERMINAL 


T3 


TERMINAL 


T4 


TERMINAL 


T2 


TERMINAL 


T5 


TERMINAL 



Queuing by Terminal 



The QCNTRL= operand may be coded on the TERMINAL macro for each 
terminal attached to the concentrator. A destination queue is generated for each 
occurrence of the QCNTRL= operand. This queuing technique requires more 
main storage than the other three queuing techniques discussed above. 



Defining Data Sets 



The PCI= operand of the line group DCB macro must specify either N or X in 
order to properly allocate and deallocate buffers on sending and receiving opera- 
tions. (See the PCI= operand in the description of the line group DCB macro 
instruction in an earlier chapter of this book.) 



Initializing a Message-Concentrating Device 



The FEATURE = operand of the INTRO macro specifies whether a concentrator 
is in the network; if present, it also differentiates between a network consisting 
entirely of concentrator-attached terminals and a network that includes terminals 
not attached to a concentrator. 



Name 


Operation 


Operand 


[symbol] 


INTRO 


...,FEATURE=(..., (CONC )) 
<^CONCO > 
( NOCONC ) 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 
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! 



CONGO \ 
I NOCONQ 

Function: Specifies the types of terminals in a concentrator network. 
Default: NOCONC. This operand may not be omitted if one or more 
concentrator-attached terminals are in the network. 
Format: CONC, CONGO, or NOCONC. 

Notes: CONC must be specified if some of the terminals in the system are con- 
nected to a remote message-concentrating device while others are not. 

CONCO must be specified if all the terminals in the system are connected to a 
message-concentrating device. CONCO takes precedence over either DIAL or 
2741 (that is, only concentrator support is provided). While CONCO does not 
permit a 2741 to function in the network as a non-concentrator, a 2741 may 
function as a terminal attached to a concentrator. 

In addition to the FEATURE = operand, the INTRO macro also must specify 
queuing by terminal (see QBY=T in the description of the INTRO macro in an 
earlier chapter). 

Handling Incoming Concentrated Messages 

This section describes the formats of incoming messages that pass through a 
message-concentrating device. It also discusses the flow of incoming messages 
and additional TCAM functions in handling incoming messages from a concentra- 
tor, including status analysis, source determination, and multiple MH execution. 

Input to TCAM from a concentrator consists of multiple logical messages received 

in a single transmission sequence. The deblocking facility is used to extract these ? 

logical messages from the incoming physical transmission. k 

Formats of Incoming Messages 

There are three levels of input messages by the time they are forwarded to their 
destinations from an incoming Message Handler. To illustrate these various 
levels, assume four terminals attached to a concentrator. Individual input mes- 
sages to a concentrator are equivalent to concentrator terminal buffers (CTBs); 
buffer in this instance is related to a concentrator's buffering scheme and bears 
no relationship to a TCAM buffer. 

Terminal A enters a single message (a CTB) to be forwarded to a destination 
station. 

Terminal B enters the first of two CTBs to be constructed (blocked) by a second 
MH as one message for forwarding to a second destination. 

The two CTBs (one each from terminals A and B) are combined by the concen- 
trator to be entered in a single transmission sequence. 

Terminal C enters a single message for a third destination. 

Terminal D enters a single message for a fourth destination. 



Terminal B enters the second (final) CTB needed to construct a logical message 
for the second destination. 



ICTBl I CTB2| I CTB3 \ CTB4 | CTBS { 



i 
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CTBs 1-5 represent the first level of messages; the concentrator receives the 
individual terminal messages in the order shown. 

PI P2 



r \ ( ^^ \ 

I CTBl I CTB2| |CTB3| CTB4 1 CTB5 1 

PI and P2 represent the second level; the concentrator combines the first two 
CTBs in this simplified example for the first physical transmission sequence (PI). 
The concentrator forwards PI to the CPU and begins receiving the next group of 
CTBs to form P2 for forwarding to the CPU. 

PI P2 



I CTBl I CTB2 I |CTB3 | CTB4 | CTB5| 

LI L2 L3 L4 L2 

L1-L4 represent the third level; when PI is forwarded to the CPU, it is directed to 
an MH that extracts the logical messages LI and L2 for forwarding to different 
destinations. Note that the first logical message (LI) corresponds to CTBl. 
However, the second logical message (L2) consists of /wo CTBs; CTB2 in the 
first transmission sequence and CTBS in the second transmission sequence. Since 
L2 is incomplete after PI is forwarded, it is queued on the destination queue as a 
partial message. The incoming MH handles P2 as it did PI, except that L2 in the 
second transmission sequence is queued on the same destination queue as L2 in 
the first transmission sequence (it is queued as the end of the message). If an 
error is detected in L2 in the second transmission sequence, TCAM still deblocks 
each logical message in P2 (each logical message goes through the MH, and an 
error bit is set — L2 is sent to its destination even though it contains an error, thus 
allowing inmessage execution). 

This example, which illustrates input from terminals attached to a concentrator, 
assumes multiple MH execution. Deblocking of physical transmissions occurs in 
the first MH. Blocking of messages across physical transmissions (as with CTB2 
and CTB5) is accomplished in a second MH. See Message Flow for Incoming 
Concentrated Messages and the discussion of the TGOTO macro in this appendix. 
Also see the SETEOM macro and Handling Logical Messages in the chapter 
Designing the Message Handler. 

Note: Incoming message headers may not cross CTB boundaries. 

Message Flow for Incoming Concentrated Messages 

The flow of messages from any message-concentrating device is similar to message 
flow for logical messages as outlined in the discussions on blocking and deblocking 
incoming logical messages (see Logical Message Flow Within the System in the 
chdiptQY Designing the Message Handler). The following example discusses 
message flow for incoming concentrated messages and should be read in conjunc- 
tion with Figure 60. The format of the data arriving at the incoming MH in a 
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where the first EOM dehmits the first logical message (LI), the second EOM 
delimits the second logical message (L2), and the third EOM delimits the final 
logical message (L3) in this transmission sequence. The message header in each 
logical message identifies the originating terminal (ID). 

1. Data is transmitted from a concentrator to the incoming MH where the PCI= 
operand of the line group DCB macro specifies either N or X. 

2. The SETEOM macro in the inblock subgroup deblocks the incoming data into 
three logical messages (from this point logical messages are processed separate- 

ly). 

To prevent deblocking of line-control and EOT characters by SETEOM and 
subsequently sending these control characters through the MH as logical 
messages, LC=OUT may be coded on the STARTMH macro to remove 
Une-control characters, and a MSGEDIT macro may be coded before SETEOM 
in the inblock subgroup to remove EOT characters. 

3. The inheader subgroup then begins execution for LI. The FORM= operand 
on the ORIGIN macro determines which terminal attached to the concentrator 
entered LL From this information supplied by the ORIGIN macro, the 
TGOTO macro (discussed later in this appendix) can determine whether to 
send this buffer of LI to a second MH. If control is passed to the second MH, 
subsequent macros in the first MH do not execute for this buffer. The second 
MH executes completely before the next buffer starts through the first MH. 
The purpose of the second MH is to handle the blocking of logical messages 
entered by terminals attached to a concentrator. It is also used to handle 
mid-batch recovery for terminals attached to a concentrator. 

The ORIGIN macro need not be reissued in the second MH; the scan pointer is 
reset to the beginning of the buffer at the start of the second MH, and header 
processing in the second MH should be handled accordingly. 

Buffers not sent to the second MH pass through the first MH in a conventional 
manner. In the first MH in the example, status analysis, using the Q ACTION 
macro, is bypassed for this message by using the MSGTYPE macro (the 
Q ACTION macro is discussed later in this appendix). 

4. Next, the inbuffer subgroup executes, where a second TGOTO macro condi- 
tionally sends text buffers not executing the inheader sub-group to the second 
MH (this is necessary since only header buffers can cause the inheader sub- 
group to execute). This TGOTO macro causes text buffers to be sent to the 
second MH for processing (the first TGOTO macro has already forwarded the 
header buffer, associated with these text buffers, to the second MH). 

5. Once MH execution is complete for LI, including execution of the inmessage 
subgroup, L2 and L3 are processing consecutively in the same manner as LI, 
including the possible use of the second MH. 

Message flow for outgoing messages is discussed in Preparing Outgoing Concen- 
trated Messages, 
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Figure 60. Message Flow for Incoming Concentrated Message 



The ORIGIN macro is used in the incoming group of a TCAM network handUng 
concentrated messages in order to identify and verify which terminal entered a 
message. The FORM= operand, described below, is specified to verify either the 
name of the source terminal (from the terminal name in the origin field of each 
CTB), or the terminal device ID (from the ID inserted by the concentrator in each 
CTB of the message). If multiple MHs are being used, the ORIGIN macro must 
be executed in the inheader subgroup before the TGOTO macro. 



The ORIGIN macro 

• identifies and verifies the source of an incoming message from a concentrator- 
attached station; 

• is required in the inheader subgroup of the MH handling incoming concentrated 
messages. 



Name 


Operation 


Operand 


[symbol] 


ORIGIN 


[,FORM=jlD h 

)name\ 
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symbol 



FORM= jiD 

Iname 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembly language symbols (see the symbol 

entry in the Glossary). 



Function: Specifies whether device id or the name in the origin field of the 

message header is used to identify and verify the source terminal. 

Default: None. If this operand is omitted, then the function described in the 

discussion of the ORIGIN macro in an earlier chapter applies. 

Format: ID or NAME. 

Notes: This operand may be used only for source determination of messages from 

concentrator-attached stations. Its use requires that the INTRO macro specify 

either CONG or GONGO on its FEATURE = operand. If ID or NAME is 

incorrectly specified, the ORIGIN macro does not expand. If the FEATURE= 

operand of the INTRO macro specifies (or defaults to) NOGONG, the ORIGIN 

macro does not expand because use of the FORM= operand is inconsistent with 

NOGONG. 



Multiple MH Execution 



If FORM=ID is specified, it may be necessary to include the GODE macro before 
ORIGIN executes in order to translate the incoming device id into the form 
specified in the DVGID= operand of the TERMINAL macro. If a concentrator- 
attached station enters a message that specifies an invalid name or ID, TGAM 
assumes that the origin is the first terminal entry following the entry for the 
concentrator. 

Once ORIGIN executes, any option fields related to the source terminal may be 
referred to from this MH. For more information on option fields, see Option 
Fields in a Concentrated-Message Network later in this appendix. 

An ORIGIN macro with the FORM= operand specified will not execute for 
messages from terminals not in a concentrator network. 

After the ORIGIN macro executes, one of the following codes is returned in 
register 15. 

Code Meaning 

X'OO' The ORIGIN macro executed successfully. 

X'04' The FORM= operand was not specified and the source terminal was 

not valid. 

X'08' The FORM= operand was specified, but the source terminal is not 

in a concentrator network. 

X'OG' The FORM= operand was specified, but the origin specified in the 

message is not a vaUd name or ID for a terminal attached to the 
concentrator entering data (the first terminal entry following the 
entry for the concentrator is assumed to be the origin). 



TGAM permits the logical messages within an incoming concentrated message to 
be forwarded selectively to any one of several MHs to be handled according to 
user needs. This faciUty is provided by coding the TGOTO macro in the inheader 
and, if needed, in the inbuffer subgroup of the incoming MH handling concentrat- 
ed messages. The TGOTO macro also provides mid-batch recovery in a second 
MH for input from concentrator-attached stations. 



( 
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TGOTO Macro Instruction 



symbol 



The TGOTO macro 

• provides communication between two Message Handlers; 

• executes only for terminals attached to a concentrator; 

• requires that the source terminal's TERMINAL macro specify either the 
LMD= operand or the MB= operand (or both); 

• requires that source determination be done in the MH in which it appears; 

• may be coded in the inheader or inbuf fer subgroup. 



Name 


Operation 


Operand 


[symbol] 


TGOTO 


MH=JnameofMHl 

jopfield j 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 



MH=jname of MH 
jopfield 



Function: Names the Message Handler to which control is passed, or names an 
option field containing the address of the MH. 
Default: None. This operand must be specified. 

Format: name of MH must be framed C ' or CLn' ' format, opfield must not 
be framed and must be the name of an option field defined by an OPTION macro. 
This option field must be defined as an address constant field either as AL4 or A. 
The field can then be initialized to an MH address by specifying the name of the 
MH in the OPDATA= operand of the TERMINAL macro. Both name of MH 
and opfield must conform to the rules for assembler language symbols. 



When TGOTO executes, no more macros of the MH are executed for the logical 
message being handled (the buffer is passed to the second MH for handUng as if it 
had been read from a station). The buffer is processed by the second MH before 
the first MH handles any more buffers. 

By determining the source terminal with the ORIGIN macro, the second MH can 
use the control blocks of the source terminal rather than using the control blocks 
of the remote message-concentrating device. 



One of the following codes, returned in register 15, describes the outcome of the 
execution of a TGOTO macro. 



Code 
X*04' 



X'08' 



Meaning 

The terminal that entered this message either is not attached to a 
concentrator or is attached, but the station's TERMINAL macro 
does not specify LMD= YES or MB = YES. Processing continued in 
the inmessage subgroup of the first MH. 

The TGOTO macro specified that the name of the second MH for 
the terminal entering the message was in an option field, but the 
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option field was not initialized by the OPDATA= operand of the 
station's TERMINAL macro. 
X*OC' The address of the second MH, specified either in the TGOTO 

macro or in an option field, is not a valid MH address. 

The SETEOM macro in the inblqck subgroup handling concentrated messages 
must specify PROCESS = YES. This is required to deblock an entire concentrated 
message into individual messages entered by the terminals attached to a concen- 
trator. However, if a concentrator-attached terminal is entering a logical message 
in two or more transmission sequences to be blocked by TCAM, the two or more 
parts of the message must be redirected from the first MH to a second MH whose 
SETEOM macro specifies PROCESS=NO. The point in the first MH at which 
TGOTO is coded to redirect the parts of the logical message is important. Since 
the first buffer of the logical message is a header buffer, it causes the inheader 
subgroup of the first MH to execute. The buffer is then passed to the second MH 
by TGOTO after the source is determined by the FORM= operand of the 
ORIGIN macro. Any subsequent buffers of this logical message in the same 
transmission as the first buffer are text buffers and do not cause the inheader 
subgroup to execute. Therefore, a TGOTO macro is required in the inbuffer 
subgroup of the first MH to send all subsequent buffers of the logical message 
(that is, all subsequent buffers included in the same transmission sequence as the 
header buffer). If the logical message is incomplete after the first transmission, 
the first buffer containing additional data of the logical message (in a later trans- 
mission sequence) is treated as a header buffer until it reaches the second MH. 
This buffer causes the inheader subgroup of the first MH to execute even through 
it is a continuation of the text portion of a logical message received in a previous 
transmission sequence. Therefore, this buffer must be handled appropriately by 
the subgroup of the first MH. As soon as the first MH identifies the source of the 
message (with the FORM= operand of the ORIGIN macro), a TGOTO macro 
must redirect this buffer to the second MH where it is treated as a text buffer, 
thereby avoiding improper handUng in the inheader subgroup of the first MH. 

Additional points that need to be considered in handling input from a concentrator 
are: 

• When a buffer is redirected to a second MH, the scan pointer is reset to the 
beginning of the buffer before execution of any macros in the second MH. 

• Do not issue a CODE macro in the second MH that would translate a buffer 
already translated by a CODE macro in the first MH. 

• The SETEOM macro specified in the second MH must specify PROCESS=NO 
(the first MH requires PROCESS=YES). 

• A buffer may be sent from one MH to another MH by the TGOTO macro only 
once. That is, once a buffer is sent to a second MH, it may not be sent from this 
second MH to another MH. 

• To prevent the SETEOM macro from deblocking line-control and EOT charac- 
ters and subsequently sending them as logical messages through the first MH, 
and possibly sending them to a second MH, code LC=OUT on the STARTMH 
macro to remove Une-control characters, and code a MSGEDIT macro in the 
inblock subgroup to delete EOT characters and "contract" the data following 
deletion (issue MSGEDIT before SETEOM). 

• Mid-batch recovery for incoming data from concentrator-attached terminals 
must be handled in a second MH. 
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Status Analysis 



Once an outgoing CTB is removed from a destination queue and forwarded to a 
concentrator, the user can delay further activity of that destination queue, pending 
subsequent incoming status information from the concentrator and its attached 
terminals. Whether outgoing message traffic resumes from the queue depends on 
the results of a user-analysis routine that examines the status information. Previ- 
ous operations that might determine a delay in subsequent transmissions to a 
terminal include such things as whether the last message to that terminal was 
transmitted successfully, whether the terminal's printer was operating correctly or 
whether a message was not accepted because a printer was not ready. Such 
information is useful in efficiently controlling subsequent output operations. 



Status analysis is provided by specifying QCNTRL=STATUS in each 
TERMINAL macro associated with the terminal for which analysis is desired. 
The QCNTRL= operand is discussed earlier in this appendix. Also, the inheader 
subgroup that executes on the incoming message (from the terminal whose data is 
to be analyzed) must contain a Q ACTION macro instruction (described below). 

The QACTION macro allows the user to take an exit to perform his analysis and 
to indicate to TCAM the appropriate action to be taken, such as proceeding to the 
next part of the data in the ouput sequence for a destination terminal or executing 
an outmessage subgroup with the user error bit (bit 20— see Appendix B ) set for 
data previously sent to a terminal. The outmessage subgroup is executed also 
when the user wishes to proceed after status is received for the last part of a 
message. 



Following are two examples of data formats that would use the status analysis 
faciUty. RS is used as a delimiter. 



Status For 
All Devices 



I RS 



Device 
id 



Data 



1 



RS 



Device 
id 



Data 



RS 



LI 



L2 



L3 



LI (the first logical message included in this transmission seuqence) contains 
status information for all terminals that provide input for this transmission. 



Device 

id I 



Status I Data 



RS 



Device 
id 



Status 



1 



RS 



Device 
id 



I Status I Data | RS 



J 



Ll 



L2 



-"Y — 

L3 



In this example, all three logical message (LI, L2, and L3) contain status informa- 
tion; note, however, that the terminal associated with L2 did not provide any 
input data for this transmission (the associated terminal accepted a message from 
the concentrator, and, in this instance, the terminal had no input message). 



QACTION Macro Instruction 



The QACTION macro 

• provides a user exit to analyze the status information given by the concentrator 
and its attached terminals; 

• allows the user to return to the MCP the processing he wants to be done for 
each attached terminal (for instance, execution of the outmessage subgroup); 

• permits output scheduling to a concentrator based on status analysis; 

• is permitted only in the inheader subgroup. 

• must be issued after the last SETEOM macro executed for this same message. 
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This macro controls output to a terminal based on status information involving an 
earlier operation by that terminal. When QCNTRL=STATUS is specified on the 
TERMINAL macro for a terminal TCAM does not execute the outmessage 
subgroup for that terminal until a QACTION macro instruction is executed for the 
terminal on subsequent input. The user also may use the QACTION macro to 
cause the user error bit (bit 20 of the message error record) to be set for executing 
the outmessage subgroup. 

When logical messages are transmitted to or from a terminal attached to a concen- 
trator, execution of the inmessage subgroup may be forced for this logical message 
either with or without the user error bit set. 

When executed, QACTION gives control to the routine whose address is specified 
in its EXIT= operand. When the user routine gains control, the following regis- 
ters contain: 

Register Contents 



3 

4 

6 

14 

15 



station control block address 
line control block address 
buffer address 
return address 
user exit address 



Do not alter the contents of register 13. The user routine performs its analysis 
and returns information to TCAM defining the processing it is to perform for one 
or several terminals (register 1 must contain the address of an area that defines 
the processing TCAM is to do). 

Among the information he returns, the user can specify for each terminal attached 
to a concentrator: 

• executing the outmessage subgroup; 

• setting the user error bit (bit 20) of the message error record; 

• preventing further output with or without previous operation pending 
(outmessage subgroup not to be executed); 

• continuing to send if multiple segments are involved in an output message, or 
resuming sending if previously stopped by above action. 

In addition, the user may specify execution of the inmessage subgroup for the 
buffer currently being processed in the MH. The format of the return area is 
discussed in the EXIT= operand description below. 



Name 


Operation 


Operand 


[symbol] 


QACTION 


TYPE^a/ ,EXIT=name 



symbol 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols (see the 

symbol entry in the Glossary ). 



i 
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TYPE= 



los 



EXIT=name 



Function: Specifies whether A- type or V-type addressing constant is generated for 

the user routine. 

Default: TYPE=V 

Format: A or V 

Notes: Specify A if the user routine is to be assembled as part of the MCP. 

Specify V if assembled separately. A indicates an A-type, and V indicates a 

V-type addressing constant. 



Function: Specifies the name of a user- written routine to be given control each 

time this macro is executed. 

Default: None. This operand must be specified. 

Format: name must conform to the rules for assembler language symbols. 

Notes: TCAM automatically saves and restores registers for this routine; the user 

need not save registers and may change the contents of registers 2 through 12. Do 

not alter the contents of registers 13 and 14. The user- written routine returns 

control to TCAM by issuing a BR 14 instruction — a return code is not required. 

TCAM expects the user routine to place, in register 1, the main-storage address of 
a field defined by the user and consisting of a byte containing the number of 
terminals involved, followed by an entry for each terminal for which action is to 
be taken. Each entry, in turn, must contain the following fields: 

1. One byte, indicating the total length (including this byte) of this entry, and 
indicating whether the device id or the terminal name is being passed. 



bitO= 

bits 1-3 
bits 4-7 = 




1 



device ID passed. 

terminal name passed. 

reserved. 

length of this entry (including this byte). 



2. An action byte 



bitO= 
bits 1-3 
bit 4= 



1 



1 



bit 5 = 



1 



user error bit (bit 20) set in the message error record, 
reserved. 

sending to this terminal is to be (or is to remain) stopped; no 
output is sent to any terminal using the same destination 
queue. This condition is reversed by an action using bit 7 be- 
low. Terminals being queued by priority level cannot be held 
using the QACTION macro unless a message was sent earlier 
to the terminal. 

execution of the outmessage subgroup must be forced even if 
the last segment sent to the terminal was not the last of the 
message. Forced execution of the outmessage subgroup causes 
the terminal error bit (bit 27) to be set in the message error 
record. 

the inmessage subgroup must be executed for this station, 
sending to this terminal must continue; the outmessage sub- 
group is executed if the last segment sent was the last segment 
of the message. 

3. A variable-length field (1-8 bytes) containing either the device id or the name 
of the terminal for which action is to be taken. 

If bits 4, 5, and 6 are set in the action byte, bits 5 and 6 take priority. That is, if a 
previous operation is pending, either the inmessage or the outmessage subgroup is 
executed. If no operation is pending, output from the queue is stopped. 



bit 6= 
bit 7 = 
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Note: An action byte of X'OO' or a device ID of X'FF' causes an entry to 
be ignored. If the user specifies an invalid action byte (for instance, bits 4 
and 7 are set), or if the QCNTRL= operand of the TERMINAL macro 
does not specify STATUS, then a X'04' return code is passed in register 15, 
with register 1 pointing to the invalid entry. No action is taken for any 
entry after the invalid one. 

If no buffers are available, X'08' is returned in register 15. Register 1, in this 
instance, points to the current entry, and no further action is taken for this or 
subsequent entries. 

Two procedures for intercepting messages, outlined below, should be followed to 
avoid losing messages queued for output (these procedures are required if the 
message queues data set is on reusable disk). 

1. When the user routine sets bit 4 in the action byte to suspend transmission to a 
terminal, messages are not intercepted as with the HOLD macro. Rather, an 
internal TCAM routine temporarily suspends transmission to the terminal. If a 
true intercept is needed, it is up to the user either to issue the functional HOLD 
macro in a Message Handler, or to enter a SUSPXMIT operator command. An 
intercept is required if a reusable disk message queues data set is being used; if 
a true intercept is not accomplished at the time TCAM implements zone 
reorganization for the disk queue, any messages being held temporarily because 
bit 4 is set will be lost. See the description of the SUSPXMIT operator com- 
mand in an earlier chapter of this book. The HOLD macro is discussed also in 
an earlier chapter as well as in Intercepting and Releasing Outgoing Messages 
in this appendix. Reorganization of a reusable disk data set is discussed in the 
chapter Defining the MCP Data Sets . 

2. If the TERMINAL macro for a terminal specifies status analysis, an internal 
TCAM routine temporarily suspends transmission to that terminal each time ^ 
data is read from its output queue. If subsequent status information from the 
concentrator indicates a situation that might prevent continued successful 
transmission to that terminal, the user either must release that message for 
transmission to its destination (by setting bit 7 of the action byte), or he must 
discontinue sending through an intercept function (by setting bit 5 of the action 
byte). When bit 5 is set, outmessage execution is forced — this causes the 

terminal error bit (bit 27) to be set for the terminal; when the outmessage 
subgroup is executed, the user must execute a HOLD macro to prevent losing 
data. The HOLD macro must include a mask that specifies bit 27 in the mes- 
sage error record. 

Example: 

Status information for three terminals is in a single CTB. The device IDs of the 
terminals are CI, C2C1, and C2C2. The user wants to continue sending to 
terminals CI and C2C2, and to stop (or continue to have stopped) output to 
C2CLThe user passes device IDs to TCAM instead of terminal names. The 
user-provided field would be: 



entry 1 



Byte 


Bit 


Hex 


Value 


Meaning 


1 




03 




number of entries 


2 










ID is passed 




4-7 


3 




length of entry 


3 




01 




action 


4 




CI 




ID 



/" 



i 
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ID is passed 

entry 2 ) 4-7 4 length of entry 

08 action 

C2C1 ID 

ID is passed 

entry 3 ) 4-7 4 length of entry 

01 action 

C2C2 ID 

Constructing Outgoing Messages for a Concentrator 

This section outlines the procedures and considerations for blocking output data 
for a single transmission that incorporates messages for a variety of destinations. 

The techniques for defining the type of queuing to be used in a concentrator 
network require using the QCNTRL= operand of the TERMINAL macro. The 
DVCID= operand of the TERMINAL macro must be used to differentiate 
between concentrators and their attached terminals. See Defining the Network 
in this appendix and the description of the TERMINAL macfo in the chapter 
Defining Terminal and Line Control Areas . A summary describing required, 
optional, and invalid use of operands of the TERMINAL macro (for concentra- 
tors and their attached terminals) are listed at the end of this appendix. 

Only one outgoing MH is used for handling messages destined for terminals 
attached to a concentrator. The MH is specified on the MH= operand of the Une 
group DCB macro. Outgoing messages to a terminal are blocked automatically 
after MH execution. 

Status analysis, performed in an input MH, may determine how output queues of 
data are to be handled, based on the user analysis of status information made 
available by the concentrator. See Status Analysis earlier in this appendix. 

Output to concentrators is achieved by using normal TCAM techniques for line 
scheduling. Consider the concentrator as a terminal with queuing by terminal 
(QBY=T specified on the TERMINAL macro) even though there may be many 
queues of data going to the concentrator. When data is available to send to any 
terminal attached to the concentrator, it is as if data were available to send to the 
concentrator; that concentrator is then scheduled for output. Send, equal, or 
receive transmission priorities apply in the same way as in TCAM without mes- 
sage concentration, and additional message queuing is not required. Further, 
non-concentrators and concentrators may be included in the same line group using 
the same type of line scheduling. 

Output to a terminal attached to a concentrator may be held by using the HOLD 
functional macro or by issuing the SUSPXMIT operator command. Intercepted 
output messages may be released with the MRELEASE macro issued in an 
appUcation program, or by issuing the RESMXMIT operator command. Operator 
control facilities to intercept or release output, as well as the application program 
facility to release output, allow the user to intercept or release messages destined 
for all terminals attached to a concentrator simply by intercepting or releasing 
messages destined for the concentrator. The HOLD macro may be issued only for 
attached terminals, not for the concentrator itself. 

The INITIATE macro must not be issued for messages to or from concentrators or 
their attached terminals, and the MSGGEN macro may not be used for generating 
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error messages to terminals attached to concentrators. Messages may not be 
transmitted in either lock or extended lock mode (see the description of the 
LOCK macro in the Designing the Message Handlers chapter). 



Message Formats 



Just as for input from a concentrator, there are three levels of data in considering 
output to 2i concentrator. The first is at the level of the message to be sent to a 
terminal attached to a concentrator. This is the amount of data that is queued as a 
message for the terminal. This unit of data is processed through the outgoing MH 
with a single execution of the outmessage subgroup. However, transmission of 
this message to the concentrator, and from there to an attached terminal may 
require multiple transmissions. The amount of data sent by TCAM to each 
terminal attached to a concentrator in each transmission is called (as it was for 
input) a concentrator terminal buffer (CTB). 

The CTB represents data at the second level. The amount of data placed in a 
CTB is determined by the QCNTRL= operand of the TERMINAL macro and 
may be less than or equal to the entire message for a destination. The insertion of 
device ID and message delimiter takes place at the level of the CTB. This inser- 
tion is accompUshed by the CTBFORM macro in the outgoing MH (the 
CTBFORM macro is discussed below). The third level is all of the data in the 
transmission sequence to the concentrator that may be made up of multiple CTBs. 
The length of the concentrated message is determined by the number and lengths 
of the CTBs. Line control needed to send the concentrated message is inserted by 
the MSGFORM macro in the outgoing MH. Line control is maintained by 
inserting Une-control characters for the entire concentrated message without 
regard to CTB boundaries. 

EOT characters are not removed from incoming messages even if LC=OUT is 
specified on the STARTMH macro. Thus, if messages are to be blocked into an 
outgoing concentrated message, replace the EOT characters with another byte of 
data, such as an idle character, using the MSGEDIT macro in the outbuffer 
subgroup. 

Illustrated below are six CTBs to a concentrator (CTB1-CTB6) that make up the 
two physical transmission sequences to the concentrator (PI and P2), and five 
logical messages to terminals attached to the concentrator (L1-L5). Note that 
logical message L2 is sent to its destination in two transmissions and is represent- 
ed by two CTBs, CTB2 and CTB4. 



PI 



P2 



ICTBl I CTB2 I CTB3| |CTB4 I CTB5 I 



CTB6| 



LI 



L2 



L3 



L2 



L4 



L5 



CTBFORM Macro Instruction 



The CTBFORM macro 

• inserts device ID at the beginning of a CTB; 

• inserts a special field in the CTB text following the device ID; 

• inserts a delimiter at the end of the CTB; 

• is required in the outbuffer subgroup of an MH handling messages destined for 
a concentrator. 



i 
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The CTBFORM macro does not require reserve characters for insertion of data. 
However, if there are reserve characters remaining in the buffer, they will be used 
for inserting device id and option field data. Reserve characters are never used for 
inserting CTB delimiter characters. 

Separator characters are not inserted if there is no space available in the buffers, 
and there are no units available. Since insertion of separator characters occurs 
just before the data is transmitted, there is no return code to indicate whether 
insertion took place. 

The CTBFORM macro must be the last macro in the outbuf f er subgroup that 
causes insertion of data (that is, the MSGEDIT and DATETIME macros must be 
coded before CTBFORM). The MSGEDIT macro should be coded in the outbuf- 
f er subgroup to replace EOT characters in messages destined for a concentrator 
(discussed in the previous section). 

The following return codes in register 15 indicate whether this macro executed 
successfully, and if unsuccessful, why. 

Code Meaning 

X*04' Separator character insertion requested; none defined. 

X'08' Insertion of opfield data requested; option field not found. 

X'OC Combination of X*04' and X'08'. 

X'lO' Insertion of device ID requested; device ID not defined. 

X' 14' Combination of X'04' and X' 10'. 

X'18' Combination of X'OS' and X*10'. 

X'lC Combination of X'04', X'OS', and X'lO'. 

X*20' Requested insertion of device ID and option field; not done (out of 
units). 



Name 


Operation 


Operand 


[symbol] 


CTBFORM 


[opfield][,DVCID= J NO j ][,ENDCHAR= JNO j | 

)yes( )yes( 



symbol 



opfield 



Function: Name of the macro. 

Default: None. Specification optional. 

Format: Must conform to the rules for assembler language symbols. 



Function: Specifies the name of an option field containing data to be inserted in 
the CTB after the device ID. 

Default: None. If this operand is omitted, data is not inserted. 
Format: Must be the same as the name of an option field defined by an OPTION 
macro. 

Notes: The first two bytes of the option field contain the offset in the CTB after 
which insertion is to begin. This position is calculated with respect to the begin- 
ning of the CTB and includes any device ID that may have been inserted. The 
maximum byte position that may be specified is 8, which corresponds to the 
maximum device ID allowed. The next two bytes of the option field specify the 
length of the data to be inserted. 
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DVCID= { NO 



NO J 
<YES J 



Function: Specifies whether device ID is to be inserted at the beginning of the CTB. 

Default: DVCID=YES 

Format: YES or NO. 

Notes: The device ID that is inserted is defined by the DVCID= chars operand of 

the TERMINAL macro. If this operand is omitted, or if it specifies YES, ID 

insertion occurs. If NO is specified, TCAM does not insert the ID. 



YEsl 



Function: Specifies whether TCAM is to insert the deUmiting character at the end 
of the CTB. 
Default: YES 
Format: YES or NO. 

Notes: The dehmiting character that is inserted is defined by the 
QCNTRL=(..., char ) operand of the TERMINAL macro. If this operand is 
omitted, or if YES is specified, TCAM inserts the character designated by the 
QCNTRL= operand on the TERMINAL macro. If NO is specified, or if the 
QCNTRL= operand does not specify char, TCAM does not attempt to insert a 
delimiting character. 

Example: 

CTBFORM COMMAND , ENDCHAR=NO 



COMMAND is the name of an option field specifying byte position 1 and length 
3, where the device ID has been specified as one character on the TERMINAL 
macro; the TERMINAL macro also specifies a CTB length of 50 bytes. After 
execution of the CTBFORM macro, the CTB begins with the one-character ID, 
continues with the three bytes of option field data, and ends with the original 50 
bytes of the CTB. The name field was omitted in this example. 



Message Flow 



Output to a concentrator consists of one or more queues of messages destined 
ultimately for terminals attached to the concentrator (see Constructing Outgoing 
Messages for a Concentrator in this appendix). TCAM removes these messages 
from the one, or several, destination queues associated with the attached terminals 
and blocks them into a single concentrated message for transmission to the 
concentrator. 



To provide control for the various destination queues that may be defined for the 
concentrator, TCAM maintains an internal queue for each concentrator. This 
internal queue is maintained automatically by TCAM and requires no user specifi- 
cation or consideration. Under control of the internal queue, a maximum of one 
message at a time is removed from a destination queue, even though several 
messages can be dequeued before transmitting a concentrated message. This 
message (or partial message) becomes the CTB, which then passes through the 
single, output Message Handler (the QCNTRL= operand of the TERMINAL 
macro allows specification of a maximum number of bytes of a message that may 
be sent in each transmission). At this time, line-control character insertion may 
be specified by the user by including the MSGFORM macro in the outbuffer 
subgroup of the MH that handles messages for the concentrator. 



< 
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Other control character insertions, optionally included by coding the CTBFORM 
macro in the outbuffer subgroup, include device IDs of attached terminals at the 
beginning of the CTB, a delimiter at the end of the CTB, and the data specified in 
an option field after the device ID (the CTBFORM macro is discussed in the 
preceding section of this appendix). The delimiter allows the concentrator to 
deblock the incoming message, and the device identifications tell the concentrator 
where to relay each individual, deblocked, outgoing message. The option field 
may contain control information for the attached terminal — its use, if required, 
depends upon the message-concentrating/deconcentrating device being used. The 
device id is specified in the DVCID= operand of the TERMINAL macro, and the 
delimiter is specified in the QCNTRL= operand of the TERMINAL macro; both 
are described in Defining tHe Network in this appendix. The option field is 
specified by an OPTION macro and is initialized by the OPDATA= operand of 
the TERMINAL macro. 

Control character insertion related to the entire outgoing transmission sequence 
takes place independently of CTB boundaries; line control characters that may be 
inserted are STX, ETB, ETX, EOT, EOA, and BOB. These must be inserted by 
issuing the MSGFORM macro. 

The amount of data that is dequeued and blocked before beginning transmission is 
determined by the BUFOUT= operand on the line group DCB macro assocated 
with this concentrator line. If program-controlled interruptions are to be taken to 
initiate subsequent dequeuing of data to be sent in this transmission, then the user 
must specify PCI=X on the associated line group DCB macro instruction. This 
olption, described fully in Line Group DCB , allocates and fills buffers on a 
program-controlled interruption basis, but deallocates (frees) buffers at block 
check time. This allows recovery from message-block-transmission errors without 
having to reconstruct the message block. If PCI=X is not specified on the line 
group DCB macro, then PCI=N must be specified. If PCI=N is specified, no 
program-controlled interruptions will be taken and the BlJFOUT= operand (also 
on the line group DCB macro) must specify enough buffers to contain the longest, 
.concentrated message that might be sent to a concentrator (that is, the size of a 
concentrated message should be limited using the CTBMAX= operand on the 
TERMINAL macro). 

After the outgoing Message Handler forwards a message to the concentrator, the 
OUTMSG macro is executed, and TC AM considers the message successfully sent. 
However, if the user desires to incorporate status analysis in his system, execution 
of the outmessage subgroup is delayed until he has an opportunity to inspect the 
status of subsequent incoming messages to determine if processing should contin- 
ue for message transmission to one or more of the terminals attached to this 
concentrator- This delay also applies to dequeuing messages from the destination 
queues. 

If the user specifies that more than one message for a given destination be de- 
queued for transmitting to a concentrator (that is, if the TERMINAL macro for 
this destination specifies either QCNTRL=(A11,...), or QCNTRL=(MSG,x), 
where x is greater than 1), messages for this destination are considered by TCAM 
to be successfully sent as they are dequeued (as opposed to after they have been 
transmitted to the concentrator), and the outmessage subgroup does not execute. 
Re-sending these messages is not possible if a transmission error occurs. Howev- 
er, if a permanent error is encountered on output to a concentrator and the 
I QCNTRL= operand specifies that only one message for a given destination be 
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dequeued for transmission, the outmessage subgroup is executed for each de- 
queued message. 



Intercepting and Releasing Outgoing Messages 



Using Macros 



Output to a terminal attached to a concentrator may be intercepted and released 
either by using macros or by entering operator commands. 



The HOLD macro instruction (described in the Designing the Message Handler 
chapter) may be coded in the inheader, inmessage, and outmessage subgroups of 
MHs handUng messages destined for terminals attached to a concentrator. The 
MRELEASE macro, coded in an application program, may be issued to release 
messages that have been intercepted due to the HOLD macro (or the SUSPXMIT 
operator command). 



Name 


Operation 


Operand 


[symbol] 


MRELEASE 


statname[,PASSWRD=chars] 



If messages for a terminal are intercepted by a HOLD macro, the MRELEASE 
macro releases those messages when its statname operand is identical to the name 
of the TERMINAL macro that defines the affected terminal. 

This macro is used also to release messages that were intercepted earlier by a 
SUSPXMIT operator command. If the SUSPXMIT command intercepts messages 
for a specific destination, then those messages may be released by replacing 
statname with the name of the TERMINAL macro that defines the affected 
terminal (identical to the procedure for releasing messages intercepted by a 
HOLD macro). However, if the SUSPXMIT command intercepts messages on a 
concentrator basis (that is, if messages to all terminals attached to a concentrator 
are intercepted with one SUSPXMIT command), then those messages may be 
released by replacing statname with the name of the TERMINAL macro that 
defines the concentrator. 



If a SUSPXMIT command is used to intercept messages on a concentrator basis, it 
is permissible to issue one or more MRELEASE macros on a terminal basis in 
order to resume transmission selectively to those terminals chosen by the user. 



Using Operator Commands 



The SUSPXMIT operator command may be used to suspend transmission to a 
specific terminal attached to a concentrator. 



control characters 


operation 


operand 


control chars 


jri 


TPrrstatname 



The manner in which tranmission is suspended for a specific terminal is the same 
as described in the Operator Control section in the TCAM Service Facilities 
chapter of this book. In order to suspend transmission to all terminals attached 
to a concentrator, replace statname with the name of the TERMINAL macro that 
defines the concentrator (see symbol in the name field of the TERMINAL 
macro). 



{ 
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The RESMXMIT operator command is used to release intercepted messages for a 
specified terminal. 



control characters 


operation 


operand 


control chars 


^release/ 


TP=statname 



The manner in which queued messages are released for a specific terminal is also 
described in the Operator Control section. To release messages for all terminals 
attached to a concentrator, replace statname with the name of the TERMINAL 
macro that defines the concentrator (see symbol in the name field of the 
TERMINAL macro). 

Operator Control Considerations 

When using the STOPLINE operator control command with logical message 
definition (LMD), the user must be aware that STOPLINE does not gain control 
until an EOM is received. This means that an EOM must be reached for every 
terminal on the line before STOPLINE gains control. With LMD, EOT does not 
equal EOM. 

Option Fields in a Concentrated-Message Network 

The COUNTER and MSGLIMIT macros in an inblock subgroup may refer to a 
concentrator's option fields any time before execution of an ORIGIN macro in a 
subsequent inheader subgroup. Once an ORIGIN macro executes, option fields 
associated with the concentrator may not be referred to from this MH. 

After ORIGIN executes, however, the option fields associated with terminals 
attached to the concentrator may be referred to by an MH on the incoming side. 
Furthermore, these option fields can be checkpointed using the CHECKPT 
functional macro (note, however, that a concentrator's option fields may not be 
checkpointed). 

A concentrator's option fields on the outgoing side may not be referred to from 
any MH. 



) 



Mid-Batch Recovery in a Concentrated-Message Network 

See TCAM I/O Error-Recovery Procedures in the Using TCAM Service 
Facilities chapter for a discussion of mid-batch recovery for non-concentrated 
messages. 

For incoming concentrated messages, recovery is not done on block boundaries. 
However, if multiple MHs are used to handle input from concentrator-attached 
terminals, the second MH may include a CANCELMG macro specifying 
LEVEL=BLK, which causes the CTB being handled to be canceled (the TGOTO 
macro, used for multiple MH execution, is described in this appendix). The 
incoming locical message is continued later with the next CTB from that source 
terminal. To accomplish this kind of recovery on input, the source terminal's 
TERMINAL macro must specify MB=YES. 

In concentrating messages for output to a destination, the outmessage subgroup of 
the MH handling the outgoing concentrated messages must contain a HOLD 
macro specifying LEVEL=BLK. Also, the destination's TERMINAL macro must 
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specify MB = YES; this causes the last CTB sent to a destination to be retransmit- 
ted. See the description of the HOLD macro in £>^5/g/img the Message Handler. 

Message Retrieval in a Concentrated-Message Network 

Message retrieval, using a combination of POINT with GET or READ macro 
instructions, works the same for terminals attached to a concentrator as it does for 
terminals not attached to a concentrator (see TCAM's Message Retrieval Facility 
in the Writing TC AM -Compatible Application Programs chapter of this book for 
a complete description of how to retrieve an already queued message from a 
DASD). 

Messages are retrieved with respect to a specific destination terminal, not the 
concentrator itself. 

Closedown Through Operator Control 

The SYSCLOSE operator command may be entered for either a quick or a flush 
closedown of a TCAM network that includes one or more message-concentrating 
devices (the SYSCLOSE command and quick and flush closedowns are discussed 
respectively in Using TCAM Service Facilities and Activating and' Deactivating 
the Message Control Program , earlier in this book). 

If the user enters a SYSCLOSE command specifying a quick closedown while a 
CTB is being transmitted, the entire CTB is sent before transmission ceases on 
that line. However, if the TERMINAL macro for the destination station that is 
accepting such a message specifies QCNTRL=...,bytecount..., then the amount of 
data sent may be less than the TCAM message being sent (where bytecount 
specifies a length less than the TCAM message being sent). If such a situation 
exists, loss of messages at restart can be avoided by scanning the message queues 
at restart (see TCAM Checkpoint/ Restart Facility); if the message queue is 
reinitialized and a scan is not performed, all messages or partial messages on the 
queue are lost. 

If the user enters a SYSCLOSE command specifying a flush closedown, the 
amount of queued data sent to a destination depends on whether status analysis is 
being performed for the destination (status analysis is discussed earlier in this 
appendix. If status analysis is not being performed, all messages are "flushed" 
from the queue and sent to their destination. If status analysis is being per- 
formed, messages are handled exactly as they are during a quick closedown 
(described above); the discussions above on bytecount and scanning the message 
queues also apply for a flush closedown where status analysis is being performed. 



( 
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Summary of Coding Requirements 

This section summarizes required and optional code for handling concentrated 
messages in a TCAM network. An incoming concentrated message consists of 
data composed of multiple logical messages. An incoming Message Handler 
deblocks the data in order to process its individual logical messages or to forward 
one or more of the logical messages to another MH for processing. The concept 
of deblocking incoming data, including coding requirements, is discussed in 
Handling Logical Messages in the chapter Designing the Message Handler ; 
additional required, optional, and invalid coding considerations for handling both 
incoming and outgoing concentrated messages follow. 









Required 














Optional 














Invalid 


Function 


Macro 


Operand 








1 Notes 


Initializing the 
Concentrator 


INTRO 


. . . [,FEATURE=(„(CONC ) )] 
^CONCO \ 
fNOCONH 


X 






CONGO specifies a mixture of 
concentrator-attached terminals 
and terminals not attached to a 
concentrator. CONCO^pecifies 
that all terminals are concen- 
trator-attached. NOCONC 
specifies that the system con- 
tains no message-concentrating 
devices. If this operand is 
omitted, NOCONC is assumed 
by default. 


Defining the 
Network 


TERMINAL 

(coded for a 
concentrator) 


. . . [,QBY=T] 
DVaD=(CONC[,integer]) 

QfeY=T 

DCB=dcbname 

RLN=integer 

TERM=type 

CTBMAX=integer 

ADDR=char 

BUFSIZE=integer 

NTBLKSZ=(blocksize,subblocksize) 

TBLKSZ=integer 

OPDATA=(data, . . .) 

QCNTRL= 

LMD= 

MB= 

QUEUES= 

DIALNO= 

LEVEL= 

CLOCK= 

CINTVL= 

ALTDEST= 


X 
X 

X 
X 
X 
X 


X 
X 
X 
X 
X 
X 


X 
X 
X 
X 
X 
X 
X 
X 
X 


Specifies queuing by station. 
Identifies terminal table entry as a 
concentrator or as an attached 
terminal. Integer specifies number 
of bytes in longest id for attached 
terminal; if omitted, one byte is 
assumed for all attached terminals. 
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Function 



Macro 



TERMINAL 

(coded for 
terminal 
attached to 
a concentrator) 



Operand 

BFDELAY= 

RETRY= 

SECTERM=YES 

COMP=YES 

UTERM=YES 

CALL= 

DVCiP=Jchars \ 
(NONEi 



Required 



Optional 

I I Notes 



QCNTRL=( MLL \ 

)(MSG[imsgcount>]/ 

^bytecount ^ 

[, STATUS]!, char]) 



,L] 



chars specifies id of concentrator- 
attached terminal (unframed hexa- 
decimal). Do not specify FF. 
Optional insertion of id is at beginning 
of each CTB destined for this terminal 
(if id insertion occurs, requires that 
outbuffer subgroup handling messages 
for this terminal contain a CTBFORM 
macro specifying DVCID=YES). 

NONE specifies that this concentrator- 
attached terminal has no id (id 
insertion does not occur for messages 
destined for this terminal). 
Controls dequeuing of outgoing 
messages to a concentrator. Required 
for first attached terminal, optional 
for others. 

ALL specifies that all messages on this 
queue are to be sent in one transmis- 
sion. If coded, the outmessage sub- 
group does not execute (with two 
exceptions; outmessage execution 
occurs if there is an initial selection 
error or if transmission is unsuccessful 
due to a lack of buffers); also, status 
analysis is not performed (that is, do 
not specify the STATUS operand). 

M^G[ymsgcount] specifies the number 
of messages to be sent (1 to 255 may 
be specified), limsgcount is omitted, 
one message per transmission is sent. 
If status analysis is desired, code MSG 
or (MSG,1) followed immediately by 
STATUS. If other than MSG or 
(MSG,1) is coded, then the outmessage 
subgroup does not execute and TCAM 
considers each message successfully 
sent as it is removed from its destina- 
tion queue (with two possible excep- 
tions; when (MSG,x) is specified, 
where x is greater than 1, outmessage 
execution occurs if there is an initial 
selection error or if transmission is 
unsuccessful due to a lack of buffers). 

bytecount specifies the maximum 
number of bytes sent as a CTB ( 1 to 
32767 maybe specified). If the end 
of the message is reached first, only 
the bytes in the message are included 
in the CTB. If STATUS immediately 



i 
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Function 



Macro 



Operand 



Required 



Optional 
I Invalid 

I r 



Notes 



DCB=dcbname 



RLN=integer 



TERM=type 
QUEUES=fonn 

LMD=jYESf 
<N0 ) 

ADDR=chars 



follows this operand, status analysis 
operates on each CTB of the message. 

L establishes priority levels for a 
group of terminals such that for any 
given transmission, no more than one 
message per terminal is sent. Requires 
that QCNTRL= also specify either 
MSG or (MSG,1), and that this 
TERMINAL macro specify LEVEL= 
II, I2, . . . Iflj where n equals the 
number of terminals to be controlled. 
Il, I2, and In are the priority levels to 
be used. 

STATUS specifies that status analysis 
is to be used in handling the queue 
generated by this TERMINAL macro. 
Requires that MSG, (MSG,1), or 
bytecount precede this operand. 

char specifies the delimiter to be 
inserted at the end of each CTB after 
MH processing (unframed hexadecimal 
characters must be specified but do 
not use FF). If character insertion 
occurs, requires that the CTBFORM 
macro specify ENDCHAR=YES. 

Specifies the name of the data control 
block for the line group in which the 
terminal is included. If coded, must 
agree with the DCB= operand on the 
TERMINAL macro that defines the 
destination queue for this terminal. 
Must agree also with the DCB= oper- 
and on the TERMINAL macro for 
the concentrator terminal entry. 
This operand is required if QCNTRL= 
is specified, otherwise optional. 

Specifies the relative line number, 
within the line group, of the commu- 
nication line between computer and 
terminal. Required if QCNTRL= is 
specified, otherwise optional. 
Must agree with RLN operand on the 
TERMINAL macro that defines the 
destination queue for this terminal. 
Must agree also with the RLN operand 
on the concentrator entry for this 
terminal. 

Specifies the terminal type. 

Specifies where message queues to be 
maintained. Required if QCNTRL= 
is specified, otherwise invalid. 

Specifies whether logical messages are 
to be entered from this terminal. 

Specifies address of remote message- 
concentrating device, and overrides 
any ADDR= operand specified on 
TERMINAL macro for a concentrator. 
If omitted, the value specified on the 
ADDR= operand of the TERMINAL 
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Function 



Macro 



Defining Data 
Sets 



Line group 
DCB 



MH Macros for 
Incoming Concen- 
trated Messages 



STARTMH 



INBLOCK 



SETEOM 



Operand 



Required 

Optional 



Invalid 



LEVEL=(integer, . . . ) 

BUFSIZE=integer 

ALTDEST=entry 

NTBLKSZ=(blocksize,subblocksize) 

TBLKSZ=integer 

OPDATA==(data, . . . ) 

MB= 



=J YES ) 
]N0 S 



SECTERM=J YES } 
(NO ) 

COMP=J YES I 
i NO { 

CTBMAX= 

QBY= 

DIALNO= 

CLOCK= 

CINTVL= 

BFDELAY= 

RETRY= 

UTERM=YES 

CALL= 

BUFOUT=\ integer [ 



MH=mhname 
PCI= 



X 
X 

X 
X 
X 
X 
X 
X 
X 



1x1 

. . . ,LMD= 



\ YES ) 
i NO S 



(no operands) 



ENDCHAR=(chars ) 
]op field) 



Notes 

macro for the concentrator is used. 
If more than one message is sent to a 
concentrator in a concentrated mes- 
sage, the first message determines 
which addressing character is used. 
This operand is used normally only 
when CTBMAX=1 is specified on the 
TERMINAL macro for the concen- 
trator (thus allowing the status 
analysis facility for concentrators that 
do not handle concentrated output). 

Specifies permissible priority levels 
used in header of message destined 
for this terminal. 



Specifies amount of data to be 
dequeued and blocked before its 
transmission. If PCIs control subse- 
quent dequeuing in this transmission, 
then PCI=X must be specified on this 
DCB. 



Provides logical message support for 
incoming concentrated messages. 
Requires an inblock subgroup. 

Identifies beginning of inblock sub- 
group for handling incoming concen- 
trated messages. Requires SETEOM 
macro. 

Deblocks incoming data from a 
concentrator to form a variable- 
length message. 

Specifies character or character 
string that delimits message. 
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Function 



Macro 



Operand 



LENGTH=( { (integer)^ ,opfield2) 
/ op field 



Required 

Optional 



Invalid 



PROCESS=' 



1 YES } 
I NO S 



REMOVE 



--{ YES } 
] NO ) 



QACTION 



EXIT=name 



,TYPE 



IvS 



TGOTO 



MH=\ name 
opfield 



ofMH I 
d S 



ORIGIN 



,FORM=J ID ) 

i NAME S 



MH Macros for 
Concentrating 
Outgoing Messages 



INITIATE 
MSGGEN 
CTBFORM 



opfield 



Notes 

Required if LENGTH= operand not 

specified, otherwise optional. 

Specifies length of message. 

Required if ENDCHAR= operand not 
specified, otherwise optional. 

Specifies whether second portion of 
original message is to be processed or 
discarded. First MH must include 
inblock subgroup whose SETEOM 
macro specifies PROCESS=YES. 
Any second MH to which an ex- 
tracted message is directed must 
include inblock subgroup whose 
SETEOM macro specifies 
PROCESS=NO. 

Removes EOM indicator from buffer. 

Controls output operations based on 
information from terminals. Requires 
that terminals being controlled have a 
TERMINAL macro specifying 
QCNTRL=. . . , STATUS, . . . 

Specifies name of user-written analysis 
routine that gains control each time 
QACTION executes. 

Specifies A-type or V-type address 
constant to be generated for user 
routine. 

Specify A if routine is assembled as 
partofMCP. 

Specify V if routine is assembled 
separately. 

Permits communication between two 
Message Handlers. 

Specifies name of MH to gain control, 
or option field containing address of 
MH. 

Determines origin of message from 
concentrator-attached terminal. 

Specifies whether device id or name 
in origin field is used to identify 
source terminal. If this operand 
omitted, TCAM executes in same 
manner as for non-concentrator 
terminals. Requires that the INTRO 
macro specify CONC or CONGO on 
its FEATURE= operand. 



Permits user to format CTBs on out- 
put. 

Specifies name of option field con- 
taining data to be inserted in CTB 
following device id. 
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Function 



Macro 



Operand 

DVCID=JN0 \ 

<YES> 



ENDCHAR=iNO ( 

KesJ 



Required 



Optional 

I Invalid 

I I 



MSGFORM 



HOLD 



LEVEL=BLK 



LEVEL=MSG 



MSGGEN 



Notes 

Specifies whether device id is to be 
inserted at the beginning of the CTB 
(see the D VCID= operand of the 
TERMINAL macro). 

Specifies whether the delimiter, spe- 
cified on the QCNTRL= operand of 
the TERMINAL macro, is inserted at 
the end of the CTB. 

Inserts line control characters on out- 
put. Issue in the outbuffer subgroup 
rather than the outheader subgroup. 

Required for mid-batch recovery of 
multi-block messages. 

Any CTB (after the first) containing 
an error is sent again when this operand 
is specified. 

Causes terminal to be intercepted 
(see description of HOLD macro). 
MSG is the default value. 
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Glossary 



The following is a listing of the communication terms used in 
this manual. For a complete listing of all communications 
terms, refer to y4 Data Processing Glossary, GC20-1699. 

accepting : the process in which a destination station acquires 
a message transmitted to it from the central computer. Enter- 
ing and accepting are functions of a station. 

accepting station : a destination station that acquires a mes- 
sage. 

access line : a switched line continuously connecting a re- 
mote station and the transmission control unit to a switching 
center (exchange). A telephone number is associated with the 
access line. 

access method : a combination of an access technique (either 
queued or basic) and a given data set organization (for instance, 
sequential, partitioned, indexed sequential, or direct) that 
allows the programmer to transfer data between main storage 
and I/O devices. 

active line : a communication line that is currently available 
for transmission of data. Contrast with inactive line . 

active station : a station that is currently eligible for entering 
and/or accepting messages on the line. A station may be active 
for entering or active for accepting, or both; the status of a 
station is determined by the status of the line it is on, by the 
type of character (+ or -) coded in the invitation list entry for 
the station, by the presence or absence of a HOLD macro in the 
outgoing group of the message handler handling outgoing mes- 
sages for this station, and by the five operator commands 
(ACTVBOTH, ENTERING, NOENTRNG, NOTRAFIC, 
SUSPXMIT, that directly affect the station's status. 

addressing characters : identifying characters, sent by the 
computer, that cause a particular station (or component) to be 
selected to accept a message sent by the computer. 

answering : a procedure by which a called party completes a 
connection (for switched lines). 

application program : a user-provided program that process- 
es the text portions of messages. Application programs run 
asynchronously with the message control program, and are 
usually located in another partition or region of main storage. 
TCAM application programs are optional; there may be many 
or none, depending on the needs of the user. 

ARU : see audio response unit. 

audio line : a communication line attached to an audio re- 
sponse unit such as the IBM 7770 Model 3 Audio Response 
Unit. An audio communication line is always switched. 

audio response unit (ARU) : a control unit that provides 
much the same functions for audio stations that a transmission 
control unit provides for nonaudio stations; in addition, it 
causes an audible response to be made to an audio inquiry. 



audio station : a unit of equipment associated with an audio 
response unit, at which keyed or dialed data is entered for 
transmission to the computer; an audio response is produced by 
the ARU as output. 

Auto Answer : a machine feature that allows either a trans- 
mission control unit or a station to respond automatically to a 
call that it receives over a switched line. 

Auto Call : a machine feature that allows either a transmis- 
sion control unit or a station to automatically initiate a call over 
a switched line. A dialing operation that originates at the cen- 
tral computer must use the Auto Call machine feature. 

Auto Poll : A machine feature of a transmission control unit 
that permits it to handle negative responses to polling without 
interrupting the central processing unit. At the end of the 
invitation list, polling is resumed automatically at the beginning 
of the list. 

available-unit queue .* a queue in main storage to which all 
buffer units are assigned initially (that is, before allocation to 
TCAM lines and application programs requiring buffers). 
Empty buffer units (that is, buffer units whose contents have 
been processed by the incoming or outgoing group of an MH, 
and that are not assigned to the main-storage message queues 
data set) are returned to the available-unit queue, from which 
they are reallocated. 

bid : in the contention form of invitation or selection, an 
attempt by the computer or a station to gain control of the line 
so that it can transmit data. 

binary synchronous communications (BSC) : data trans- 
mission in which character synchronization is controlled by 
timing signals generated by the device that originates a message 
(and the device that obtains the message recognizes the sync 
pattern at the beginning of the transmission — the devices are 
locked in step with one another); contrast with start-stop 
transmission . 

block : that portion of a message terminated by an EOB or 
ETB line-control character or, if this is the last block in the 
message, by an ETX or EOT line-control character. When 
end-of-block checking is specified in the STARTMH macro, 
messages are checked for certain types of transmission and 
user-specified logical errors on a block-by-block basis. 

blocking : for an incoming operation, the combination of 
multiple incoming transmissions to form a single logical mes- 
sage; for an outgoing operation, the removal of messages 
queued for terminals attached to a concentrator, and the subse- 
quent combining of these messages into a single transmission to 
the concentrator ( 5ee also reblocking). 

BSC : see binary synchronous communications . 

buffer : an area in main storage into which a message seg- 
ment is read, or from which a message segment is written. 
Buffers are temporary data-holding areas that compensate for 
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the difference between the rate at which data can be entered 
from or accepted by a station and the rate at which it can be 
processed by the central processing unit; buffers also may be 
used as work areas in TCAM. The size of TCAM buffers is 
designated by the user. (See also hardware buffer .) 

buffer allocation : the assignment of buffers by TCAM to 
lines or application programs in preparation for receiving mes- 
sage segments from stations on the lines or from application 
programs. (See also dynamic buffer allocation and static 
buffer allocation .) 

buffer deallocation : for a sending operation, deallocation 
consists of returning the units that compose the buffer to the 
available-unit queue after the data in these units has been sent 
to its destination station or application program; for a receiving 
operation, deallocation consists of transferring full buffers from 
the line or application program to which they were assigned to 
the incoming group of the MH that is to process the message 
segments they contain. 

buffer prefix : a control area contained within each TCAM 
buffer. The prefix for the buffer containing the first segment of 
a message is 30 bytes, while the prefix for each buffer contain- 
ing a subsequent segment of the message is 23 bytes. The user 
must allow room for the buffer prefix when he specifies his 
buffer size. TCAM fills the prefix area with buffer control 
information. 

buffer unit : the basic building block from which TCAM 
buffers are constructed. All units in a particular TCAM system 
are the same size; this size is specified by the KEYLEN= ope- 
rand of the INTRO macro. 

buffer-unit pool : all the buffer units in a particular TCAM 
system together constitute the buffer-unit pool for that system. 
The number of units in the pool is equal to the sum of the integ- 
ers specified by the LNUNITS= and MSUNITS= operands of 
the INTRO macro. 

buffered terminal : a terminal having a hardware buffer. As 
used in this book, a buffered terminal is an IBM 2740 Model 2 
station or IBM 2770 station whose TERMINAL macro specifies 
BFDELAY=integer. 

calling : a procedure that establishes a connection over a 
switched line; a series of electrical signals, corresponding to the 
telephone number of the station or computer with which con- 
tact is to be made, are sent down the line; these pulses or notes 
cause automatic switching equipment belonging to the common 
carrier to establish the connection, if the party being called is 
free to accept the call. (Also referred to as dialing. ) 



cascade entry 

a cascade list. 



an entry in the terminal table associated with 



cascade list : a list of pointers to single, group, or process 
entries. A message is queued for the valid entry in the list with 
the fewest messages queued for it. 

central processing unit (CPU) : a unit of a computer that 
controls interpretation and execution of instructions. 

channel program block (CPB) : a TCAM control block 



used in the transfer of the data between buffer units and mes- 
sage queues maintained on disk. The CPB= operand of the 
INTRO macro specifies the number of CPBs to be provided in a 
TCAM system. 

checkpoint data set : an optional TCAM data set that con- 
tains the checkpoint records used to reconstruct the MCP envi- 
ronment after closedown or system failure, when the TCAM 
checkpoint/restart facility is utilized. 

checkpoint records : records, located in the checkpoint data 
set, that are used to reconstruct the MCP environment upon 
restart following closedown or system failure. There are four 
types of checkpoint records: environment records, incident 
records, checkpoint request records, and a control record. 

checkpoint request record : a checkpoint record taken as a 
result of execution of a CKREQ macro issued in an application 
program; the record contains the status of a single destination 
queue for the application program. The latest checkpoint re- 
quest record for a message queue is used during restart to cause 
sending from that queue to the application program to begin 
with the message that follows the last message sent to the pro- 
gram from that queue at the time the checkpoint request record 
was taken, rather than with the message following the last 
message marked serviced. 

checkpoint/restart : a TCAM facility that records the status 
of the teleprocessing network at designated intervals or follow- 
ing certain events. Following system failure or closedown, the 
checkpoint/restart facility uses the records it has taken to re- 
store the message control program environment as nearly as 
possible to its status before the failure or closedown. 

CIB : see command input block. 

closedown : an orderly deactivation of the MCP by either an 
MCPCLOSE macro instruction issued in an application pro- 
gram or an operator command. See quick closedown and 
flush closedown. 

cold restart : start-up of a TCAM message control program 
following either a flush closedown, a quick closedown, or a 
system failure. A cold restart ignores the previous environment 
(that is, the MCP is started as if this were the initial start-up), 
and is the only type of restart possible when no 
checkpoint/restart facility is used. 

command input block (CIB) : buffer-like areas that contain 
operator commands entered at the system console. Space is 
allocated for them dynamically when needed, and the main 
storage assigned to a CIB is freed once the operator command 
contained within the CIB has been processed. Only one CIB 
need be specified for operator commands entered from the 
system console. 

common carrier : in communications, a government- 
regulated private company that furnishes the general public 
with telecommunications services; a telephone or telegraph 
company. 

component : an I/O device associated with a station. 

component entry : a terminal entry that defines a component 
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of a station that maybe individually addressed; if more than one 
component of a station may be individually addressed, a com- 
ponent entry may be required for each. This entry is defined by 
a TERMINAL macro. 

computer : in this publication, the central processing unit in 
which the TCAM message control program is located. 

concentration : The process of combining multiple messages 
into a single message for transmission. 

concentrator : Any device that either combines multiple 
incoming messages into a single message (concentration), or 
extracts individual messages from data sent in a single transmis- 
sion sequence (deconcentration). 

concentrator terminal buffer : the amount of data in indi- 
vidual messages transmitted either to or from a concentrator. 
Buffer in this instance bears no relationship to a TCAM buffer. 



serves as a logical connector between the problem program and 
a data set. The data control block also can provide control 
information for any transfer of data. A data control block must 
be created for each TCAM data set except a message queues 
data set residing in main storage; a DCB macro instruction 
creates a data control block. 

Data set : 

1 . a named, organized collection of logically related records 
(program data set). The information is not restricted to a 
specific type, purpose, or storage medium. Among the data 
sets specifically related to TCAM are the line group data 
sets, the message queues data sets, the checkpoint data set, 
the message log data set, and the input and output data sets 
for a TCAM-compatible application program. 

2. a device containing the electrical circuitry necessary to 
connect data processing equipment to a communication 
channel; also called a subset, Data-Phone*, 
modulator/demodulator, or modem. 



constructing : see blocking. 

contention : classically, a line-control scheme in which sta- 
tions on a Hne compete for the use of that unused Hne; the 
station that is successful in gaining control of the line is able to 
transmit. In a TCAM system, the term is applied to any point- 
to-point line configuration when the station on the line does not 
use polling and addressing characters. 

continuation restart : a restart of the TCAM message 
control program following termination of the message control 
program because of system failure; the TCAM 
checkpoint/restart facility restores the MCP environment as 
nearly as possible to its condition before failure. 

control characters : characters transmitted over a line that 
are not message data, but which cause certain control 
operations to be performed when encountered by the computer, 
transmission control unit, or station; among such operations are 
polling and addressing, message delimiting and blocking, 
transmission-error checking, and carriage return. 

control record : a record, included in a checkpoint data set, 
that keeps track of the correct environment, incident, and 
checkpoint request records to reconstruct the message control 
program environment during restart. 

CPB : see channel program block . 

CPU : see central processing unit. 

CTB : see concentrator terminal buffer. 

DASD : direct-access storage device, also referred to as disk . 
The DASD devices supported by TCAM are the IBM 2314 
Direct Access Storage Drive and the IBM 3330 Disk Drive. 

data collection : a telecommunications application in which 
data from several locations is accumulated at one location (in a 
queue or on a file) before batch processing. 

data control block (DCB) : an area of main storage that 



DCB : see data control block. 

dead-letter queue : the destination queue for the station or 
application program named by the DLQ= operand of the 
INTRO macro instruction. If an invalid destination is detected 
in a message header by a FORWARD macro instruction, and if 
no user exit is specified in the FORWARD macro, that message 
is sent to the dead-letter queue. 

deblocking : The process in a TCAM network whereby 
individual logical messages are extracted from an incoming 
transmission sequence. The resulting logical messages are 
processed individually by one or more incoming message 
handlers. 

deconcentration : the process of extracting individual 
messages from data sent in a single transmission sequence (see 
concentrator). 

delimiter macro instruction : a TCAM macro instruction 
that classifies and identifies sequences of functional macro 
instructions and directs control to the appropriate sequence of 
functional macro instructions. 

destination : the place to which a message being handled by a 
TCAM message handler is to be sent. A destination may be 
either a station defined by a TERMINAL macro, a group of 
stations defined by a TLIST macro, or an appHcation program 
defined by a TPROCESS macro. One or more destinations 
may be specified in fields of the message header that are 
checked by a FORWARD macro, or a single destination may be 
specified for all messages handled by a particular inheader 
subgroup by means of the DEST= operand of a FORWARD 
macro issued in that subgroup. 

destination field : a field in a message header containing the 
name of a station or application program to which a message is 
directed. 

destination queue : a queue on which messages bound for a 
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particular destination are placed after being processed by the 
incoming group of a Message Handler. A separate destination 
queue is created for each station defined by a TERMINAL 
macro specifying queuing by terminal, one for each line whose 
stations are defined by TERMINAL macros specifying queuing 
by line, and one for each application-program process entry 
(defined by a TPROCESS macro) to which the application 
program may direct GET or READ macros. Destination 
queues are maintained in message queues data sets that may be 
located on disk or in main storage. Queuing messages by 
destination permits overlap of line usage in I/O operations. See 
also process queue . 

destination station : a station that accepts a message sent to 
it by the outgoing group of the message handler that is 
specified for the line to which the accepting station is assigned. 

dialing : see calling. 

dial line : see switched line . 

direct-access storage device : see DASD . 

disabling the line : a process whereby TCAM causes the 
computer to condition either the transmission control unit or 
the audio response unit to ignore incoming calls on a switched 
line. Once this is accomplished, the line is available for TCAM 
to send queued messages to a station on that line. See enabling 
the line. 

disk : see DASD . 

distribution entry : an entry in the terminal table associated 
with a distribution list. A distribution entry is created by a 
TLIST macro. 

distribution list : a list of single, group, cascade, or process 
entries; when a message is directed to the distribution entry 
associated with this list, TCAM sends the message to each 
destination named in the list. 

dynamic buffer allocation : the assignment of buffers to a 
line on an as-needed basis, after a message has started coming 
in over the line. Dynamic allocation occurs following 
program-controlled interruptions, and is specified by the PCI= 
operand of the line group DCB macro. See also static buffer 
allocation . 



EBCDIC 

Code. 



Extended Binary Coded Decimal Interchange 



enabling the line : a process whereby TCAM causes the 
computer to condition either the transmission control unit or 
the audio response unit to respond to incoming calls on a 
switched line. See disabling the line . 

end-of-address (EOA) character : 

1 . a control character or characters transmitted on a line to 
indicatethe end of nontext characters (for example, 
addressing characters). 

2. a TCAM character that must be placed in a message if the 
system is to accommodate routing of that message to several 
destinations; the character must immediately follow the last 



destination code in the message header; and must also be 
specified by the EOA= operand of the FORWARD macro 
for the message. 

entering : the process in which a station places on the line a 
message to be transmitted to the central computer (a station 
enters and accepts messages, while the central computer sends 
and receives messages). 

environment record : a record of the total teleprocessing 
environment at a single point in time. The environment record 
resides in the checkpoint data set; at restart time, an 
environment record is updated by the contents of incident 
records that were taken after the environment record was 
taken, and the updated environment record then reconstructs 
the message control program environment as it existed before 
MCP closedown or system failure. 

EOA : see end-of-address character . 

error record : five bytes assigned to each message being 
processed by a message handler; these bytes indicate physical or 
logical errors that have occurred during transmission on the line 
or during subsequent processing or queuing of the message, and 
are checked by error-handling macros in the inmessage and 
outmessage subgroups of a message handler. Also called 
message error record. 

error-recovery procedures (ERP) : a set of internal 
TCAM routines that attempt to recover from transmission 
errors. 

exchange : a communications switching center. 

extended lock mode : a type of lock mode wherein a station 
is locked for the duration of several inquiry-response cycles. 
Compare with message lock mode; see also lock mode. 

extracting : see deblocking 

FEFO (first-ended first-out) : a queuing scheme whereby 
messages on a destination queue are sent to the destination on a 
first-ended first-out basis within priority groups. That is, 
higher-priority messages are sent before lower-priority 
messages; when two messages on a queue have equal priority, 
the one whose final segment arrived at the queue earliest is sent 
first. 

FIFO (first-in first-out) : a queuing scheme whereby 
equal-priority messages on the same destination queue are sent 
in the order that their first segments arrived at the queue. 

flush closedown : a closedown of the TCAM message control 
program during which incoming message traffic is suspended 
and queued outgoing messages are sent to their destinations 
before closedown is completed; this form of termination is 
known as a flush closedown because unsent messages are 
flushed from the message queues. See also quick closedown . 

functional macro instructions : TCAM macros that perform 
the specific operations required for messages directed to the 
message handler. See also delimiter macro instruction . 
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group addressing : the capability of all terminals on a 
multipoint line recognizing addressing characters, but only one 
of the terminals responds. 



incoming group : that portion of a message handler designed 
to handle messages arriving for handling by the message control 
program. See also outgoing group . 



group entry : an entry in the terminal table associated with a 
group of terminals having the Group Code machine feature. 

half-duplex : a communication line over which transmissions 
can occur in either direction, but only in one direction at a time. 

hardware buffer : a buffer that is located in a station, as 
opposed to the buffers for the TCAM MCP, which are located 
in the computer. The IBM 2740 Communication Terminal 
Model 2, for example, contains a hardware buffer that 
accommodates up to 120 characters. See also buffered 
terminal . 

header : that portion of a message containing control 
information for the message; a header might contain one or 
more destination fields, the name of the originating station, an 
input sequence number, a character string indicating the type of 
message, a priority level for the message, etc. The message 
header is operated on by macros in the inheader and outheader 
subgroups of the message handler. 

header buffer : a buffer containing a header segment. 

header segment : a message segment containing all or part of 
the message header. 

identification characters (ID characters) : characters sent 
by a BSC station on a switched line to identify the station. ID 
characters can also be assigned to the computer (by the 
CPUID= operand of the INVLIST macro); in this case, the 
computer and the station can exchange ID sequences. TWX 
stations also use ID characters. 

idle : describes a line that is not currently available for 
transmission of data because IDLE was coded in the OPEN 
macro for the line group data set containing the line. Such a 
line may be activated by a STARTLINE operator command. 

inactive line : a communication line that is not currently 
available for transmitting data. Contrast with active line . 

inactive station : a station that is currently ineligible for 
entering and/or accepting messages. A station may be inactive 
for entering or inactive for accepting, or both; the status of a 
station is determined by the status of the line it is on, by a 
special character (+ or -) coded in the invitation list entry for 
the station, by the presence or absence of a HOLD macro in the 
outgoing group of the message handler handling outgoing 
messages for this station, and by the five operator commands 
(ACTVBOTH, ENTERING, NOENTRNG, NOTRAFIC, 
SUSPXMIT) that directly affect the station's status. 

incident record : a checkpoint record residing in the 
checkpoint data set on a DASD; an incident record logs a 
change in station status or in the contents of an option field that 
occurred since the last environment record was taken. Incident 
records update the information contained in environment 
records at restart time after a closedown or system failure. 



incoming message : a message being transmitted from a 
station to the computer. 

initiate mode : a function provided by an incoming message 
handler whereby TCAM sends the segments of a message from 
a destination queue to the destination as soon as possible after 
they are placed on the queue, regardless of whether the entire 
message has arrived at the destination queue. The INITIATE 
functional macro is coded to achieve this capability. 

input : of or related to a message transmission that involves 
entering data at a station or receiving data at the computer. 

input data set : a logical data set for a TCAM-compatible 
application program. The input data set contains all messages 
or records being sent to the application program from a single 
process queue. Though it is not located in a physical medium, 
the input data set requires a DD statement and a DCB macro 
for its definition and must be activated and deactivated by 
OPEN and CLOSE macros. Sqq also output data set. 

input DCB : a data control block that defines an input data 
set. This DCB is created by an input DCB macro. 

input sequence number : a means of ensuring that messages 
are received from a source in the correct order; the user may 
place a sequence number in the header of each message entered 
by a station or application program, and code a SEQUENCE 
macro in the incoming group of his message handler. The 
SEQUENCE macro checks the sequence number for each 
message; if the number is not one more than that assigned to 
the previous message received from that origin, a bit is turned 
on in the message error record. 

inquiry processing : a TCAM application in which the 
message control program receives a message from a station, 
then routes it to an application program that processes the data 
in the message and generates a reply; the reply is routed by the 
message control program to the inquiring station. Response 
time often may be shortened by specifying the lock mode (by a 
LOCK macro in the message handler) and by locating the 
message queues data set containing the queues for the 
application program in main storage. 

intercepted station : a station to which no messages may be 
sent. A station is intercepted by issuing a HOLD macro 
instruction in the outmessage subgroup of a message handler; 
the suspension is either for a specified time interval or until 
either an operator command or an application-program macro 
instruction is issued to release messages held for the intercepted 
station. 

invalid destination : a destination specified for a message 
that does not correspond to a valid terminal-table entry. 

invitation : the process in which the computer contacts a 
station to allow the station t'o transmit a message if it has one 
ready. 

invitation delay : a period of time (specified by the INTVL= 
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operand of the line group DCB macro), during which outgoing 
messages are sent to nonswitched polled stations for which 
receiving has priority over sending (because CPRI=R is coded 
in the line group DCB macro). This delay is observed for all 
such stations on a line when the end of the invitation list for 
that line is reached. The delay in polling is observed for such 
stations whether or not the computer has any messages to send 
them. If no invitation delay is specified for such stations, no 
messages can be sent to them. 

invitation list : a series of sets of polling characters or 
identification sequences associated with the stations on a line; 
the order in which sets of polling characters are specified (in the 
INVLIST macro for the line) determines the order in which 
polled stations are invited to enter messages on the Une. 

inward WATS : a service provided by the telephone 
company, whereby all incoming calls from within a prescribed 
area are charged to the receiving subscriber at a flat rate. See 
also WATS. 

LCB : see line control block. 

line : the communications medium linking the computer to 
one or more remote stations; message transmission occurs over 
this medium. See also nonswitched line, switched line, 
point-to-point line , and multipoint line . 

line control : the scheme of operating procedures and control 
signals by which a telecommunications system is controlled. 

line control block (LCB) : an area of main storage 
containing control information for operations on a line; one 
LCB is maintained by TCAM for each line in the system. 



lock mode : a TCAM facility, invoked in a message handler 
by the LOCK macro, whereby a station entering an inquiry 
message for an application program is held on the line by the 
message control program until a response has been returned to 
it by the application program. Using lock mode decreases 
response time because there are no interruptions on the line 
before a response is returned. If LOCK is executed and 
CONV=YES is coded in the STARTMH macro, tete-a-tete 
interaction (defined in this Glossary) is in effect for the station. 
A station may be placed in lock mode either for the duration of 
a single inquiry and response ( message lock mode) or for the 
duration of several inquiry-response cycles ( extended lock 
mode). The type of lock mode is specified in the LOCK macro. 

log : a collection of messages or message segments placed on a 
secondary-storage device for accounting or data collection 
purposes. The TCAM logging facility is invoked by a functional 
macro instruction issued in a message handler. 

log data set : a data set consisting of the messages or message 
segments recorded on a secondary-storage medium by the 
TCAM logging facility. A log data set is defined by means of a 
BSAM DCB macro instruction that is issued with the DCB 
macro instructions defining the line group data sets, the 
message queues data sets, and the checkpoint data set. 

logical message : a unit of data defined by the user by coding 
the SETEOM functional macro. 

logtype entry : an entry in the terminal table associated with 
a queue on which complete messages reside while awaiting 
transfer to the logging medium (a logtype entry is not needed if 
message segments only are to be logged). A logtype entry is 
created by a LOGTYPE macro. 



line-control characters : characters that control 
transmission of data over a line; for example, line-control 
characters delimit messages, cause transmission-error checking 
to be performed, indicate whether a station has data to send or 
is ready to receive data. 

line entry : a terminal entry that defines a switched line that 
is used for input or input/output operations. The entry is 
defined by specifying UTERM=YES on the TERMINAL 
macro. 

line group : a set of one or more communication lines of the 
same type, over which stations with similar characteristics can 
communicate with the computer. 



MCP : see message control program . 

message : for a TCAM system that defines logical messages, a 
unit of data defined by the user by coding the SETEOM 
functional macro; if logical messages are not defined, a unit of 
data received from or sent to a station that is terminated by an 
EOT or ETX control character or, if the CONV= operand of 
the STARTMH macro is coded CONV=YES, by an EOB or 
ETX control character. A TCAM message is often divided into 
a header portion, which contains control information, and a 
text portion, which contains the part of the message of concern 
to the party ultimately receiving it. 

message concentration : see concentration . 



line group data set : a message control program data set 
consisting of all the lines in a line group; the messages that are 
transmitted on these lines constitute the data in this data set. A 
line group data set is defined by a line group DCB macro 
instruction and by a DD statement for each line in the line 
group. 



message control program (MCP) : a set of user-defined 
TCAM routines that identify the teleprocessing network to the 
System/370 Advanced Operating System, establish the line 
control required for the various kinds of stations and modes of 
connection, and control the handling and routing of messages 
to fit the user's requirements. 



line group DCB : a data control block created by a line group 
DCB macro instruction; information in the data control block 
defines the line group to TCAM. 

local station : a station whose control unit is connected 
directly to a computer data channel by a local cable. See 
remote station. 



message error record : see error record. 

message handler (MH) : a sequence of user-specified 
TCAM macro instructions in the message control program that 
examine and process control information in message headers, 
and perform functions necessary to prepare message segments 
for forwarding to their destinations. One message handler must 
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be assigned to each line group by the MH= operand of the line 
group DCB macro, and one must be assigned to each 
TCAM-compatible application program by the MH= operand 
of the PCB macro. The incoming group of an MH handles 
messages received from either an originating station or an 
application program; the outgoing group of an MH handles 
messages before their being sent to a destination station or 
application program. 

message lock mode : a type of lock mode wherein a station 
is locked for the duration of a single inquiry and response. 
Compare with extended lock mode; see also lock mode. 

message priority : refers to the order in which messages in a 
destination queue are transmitted to the destination, relative to 
each other. Higher-priority messages are forwarded before 
lower-priority messages. Up to 255 different priority levels may 
be assigned to a single destination (by the LEVEL= operand of 
the TERMINAL or TPROCESS macro). The priority for each 
message sent to the destination may be specified in the message 
header or assigned by a PRIORITY macro; in either case, a 
PRIORITY macro should be coded in the inheader subgroup 
handling the message. 

message queue : see destination queue . 

message queues data set : a TCAM data set that contains 
one or more destination queues. A message queues data set 
contains messages that have been processed by the incoming 
group of a message handler and are waiting for TCAM to 
dequeue them, route them through an outgoing group of a 
message handler, and send them to their destinations. Up to 
three message queues data sets (one in main storage, one on 
reusable disk, one on nonreusable disk) may be specified for a 
TCAM message control program. 



message segment 

single buffer. 



the portion of a message contained in a 



message switching : a telecommunications application in 
which a message is received from a remote station, stored until 
a suitable outgoing line is available, and then transmitted to its 
destination station. TCAM message switching can be handled 
entirely by the message control program. 

MH : See message handler. 

mid-batch recovery : the ability to recover from permanent 
text errors encountered in any block of data following the first 
block in a multiblock message. 

mixed environment : a system in which TCAM and TSO 
tasks concurrently share all necessary system resources. 

multipoint line : a nonswitched line that connects several 
remote stations to the computer. 

nonswitched line : a communication line that links stations 
for a continuous period, or for regularly recurring periods; also 
known as a private, leased, or dedicated line. 

nontransparent mode : a mode of binary synchronous 



transmission in which all control characters are treated as 
control characters (that is, not treated as text). See transparent 
mode . 

on-line test (OLT) : an optional TCAM facility that permits 
either a system console operator or a remote station operator to 
test transmission control units and remote stations to find out if 
they work properly. 

operator command : a command entered either at an 
operator control station or at the system console to examine or 
alter the status of the telecommunications network during 
execution. 

operator control station : a station eligible to enter operator 
commands. An application program and the system console 
may also serve as operator control stations. Operator control 
stations are designated as such by the PRIMARY= operand of 
the INTRO macro and by the SECTERM= operand of the 
TERMINAL and TPROCESS macros. See also primary 
operator control station and secondary operator control station . 

option field : a storage area containing data relating to a 
particular station, component, line, or application program; 
certain message handler routines that need source- or 
destination-related data to perform their functions have access 
to data in an option field. User-written routines also have 
access to data in an option field. Option fields are defined by 
OPTION macros and initialized for each station, line, 
component, or application program by the OPDATA= operand 
of the TERMINAL or TPROCESS macro. 

option tables : a storage area containing option fields related 
to individual stations, components, lines, or application 
programs. 

origin : a station or application program from which a 
message or other data originates. See also destination . 

outgoing group : that section of a message handler that 
manipulates outgoing messages after they have been removed 
from their destination queues. The outgoing group has three 
types of subgroups — the outheader subgroup, which executes on 
outgoing header segments; the outbuffer subgroup, which 
executes on each outgoing segment; and the outmessage 
subgroup, which does not execute until after the message has 
been sent to its destination, if possible. See also incoming 
group . 

output data set : a logical data set for a TCAM-compatible 
application program. The output data set contains the 
messages or records returned from the application program to 
the message control program by a process entry in the terminal 
table. An output data set is defined by a DD statement and a 
DCB macro, and must be activated and deactivated by OPEN 
and CLOSE macros. See also input data set . 

output DCB : a data control block created by an output DCB 
macro. One output DCB is required for each output data set. 

output sequence number : a number placed in the header of 
a message by TCAM that determines the order in which 
messages were sent to a destination by the computer. When 
specified in an outheader subgroup, the SEQUENCE macro 
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places an output sequence number in the header of each 
outgoing message; this sequence number is one greater than the 
sequence number for the last message sent to this destination. 
See also input sequence number . 

path switch : a one-byte field in the option table that 
determines whether a given subgroup in an MH is to be 
executed for the message. Path switches are initialized by an 
operand of the TERMINAL or TPROCESS macro and may 
subsequently be modified by a PATH macro or by a 
combination of OPTFIELD and DATOPFLD operator 
commands. 

physical transmission : the amount of data entered on a line 
during an entire transmission sequence, from the first byte of 
data to the end-of -transmission character. 

point-to-point line : a communication line that connects a 
single remote station to the computer. It may be either 
switched or nonswitched. 

poUing : a noncontention line management method whereby 
the computer invites remote stations on multipoint nonswitched 
lines and remote terminals on point-to-point lines to enter 
messages. The computer contacts stations in the order specified 
by the invitation list; each station contacted is invited to enter 
messages. 

polling characters : a set of identifying characters peculiar to 
either a station or a component of that station; a response to 
these characters indicates to the computer whether the station 
has a message to enter. 

prefix : see buffer prefix . 

primary operator control station : an operator control 
station that receives, in addition to the responses to commands 
entered by it, the operator awareness message (lEAOOOI, 
described in TCAM I/O Error-Recording Facility in the chapter 
Using TCAM Service Facilities is sent whenever an I/O error 
occurs and TCAM's error-recovery procedures are unsuccessful 
in correcting it. The primary operator control station is 
designated by the PRIMARY= operand of the INTRO macro. 
Compare with secondary operator control station. 

priority : see message priority and transmission priority. 

process entry : a terminal entry that represents an 
application program. One must be defined (by means of a 
TPROCESS macro) for each queue to which an application 
program can issue a GET or READ and at least one must be 
defined for all PUTs or WRITEs from the same application 
program. 

process queue : a destination queue for an application 
program (see destination queue). A process queue is defined by 
a TPROCESS macro. 

queue : a set of items consisting of: 

1 . a queue control block (an area in main storage containing 
control information for the queue), and 

2. one or more ordered arrangements of items (the items may 
be messages, main-storage addresses, etc.). 



quick closedown : a closedown of the TCAM message 
control program that entails stopping message traffic on each 
line as soon as any messages being sent or received at the time 
the request for closedown is received are transmitted. See also 
flush closedown. 

read-ahead queue : an area of main storage from which an 
application program obtains work units in advance of their 
being requested by the application. 

reblocking : the ability of an outheader subgroup to divide 
outgoing messages into logical blocks of data based on a 
maximum size or a maximum number of subblocks per block; 
the MSGFORM functional MH macro provides this capability. 

receiving : the process in which the central computer obtains 
a message from a remote station (the message is entered by the 
station). Receiving and sending are functions of the central 
computer. 

record : a logical unit of data, the length of which is defined 
by the user through the use of operands of the input or output 
DCB macro and delimiting characters in the message. 

relative line number : a number assigned by the user to a 
communications line of a Hne group at system generation time 
or MCP execution time. If a line group is defined at system 
generation time by a UNITNAME macro, the lines in the group 
are assigned relative line numbers according to the order in 
which their hardware addresses are specified in the UNIT= 
operand of UNITNAME; the line whose address is specified 
first is relative line number one, that address specified second is 
relative line number two, etc. If a line group is defined at MCP 
execution time by concatenated DD statements, the order in 
which the DD statements for the lines in the line group are 
arranged determines the relative line numbers for the lines. 
The line whose DD statement appears first is relative line 
number one, the statement that appears second is relative line 
number two, etc. 

remote station : a station that is connected to a computer 
data channel through either a transmission control unit or an 
audio response unit. See also local station . 

retry : an error-recovery procedure in which the current block 
of data (from the last EOB or ETB) is re-sent a prescribed 
number of times, or until accepted or entered correctly. 

scan pointer : a pointer that refers to the proper header field 
when the macro that acts upon that field is given control. Some 
user-specified macro instructions use this pointer to locate the 
field on which they act and automatically move the pointer to 
the next field before passing control to the next macro. The 
user must be aware of the positioning of the scan pointer as he 
designs his message handler. 

secondary operator control station : a station that can 
send operator commands and can receive related responses, but 
not internally-generated error messages (with one exception: 
when a primary operator control station other than the system 
console becomes inoperative, message lEAOOOI is sent to the 
system console, in this instance a secondary operator control 
station, stating that the primary operator control station is 
inoperative). Compare with primary operator control station. 
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The secondary operator control station is designated by the 
SECTERM= operand of the TERMINAL or TPROCESS 
macro instruction. 



segment : the portion of a TCAM message contained 



ma 



single buffer. 



selection : the process whereby the computer contacts a 
remote station to send it a message. 

sending : the process in which the central computer places a 
message on a line for transmission to a station (the station 
accepts the message). Sending and receiving are functions of 
the central computer. 

sequence number : see input sequence number and output 
sequence number. 

single entry : an entry in the terminal table associated with a 
single station or station component; one such entry must be 
created (by a TERMINAL macro) for each station in the 
TCAM system not defined by a group entry. 

start-stop transmission : data transmission in which each 
character being transmitted is preceded by a special control 
signal indicating the beginning of the sequence of data bits 
representing the character, and is followed by another control 
signal indicating the end of the data-bit sequence (character 
recognition by the device that obtains the data depends on the 
presence of these control signals for each character); contrast 
v^'iihbinary synchronous communications. 

static buffer allocation : the assignment to a line, before 
transmission over that line, of all buffers to contain the 
transmitted data. When PCI=N or PCI=R is coded in the line 
group DCB macro, the number of buffers specified by the 
BUFIN= or BUFOUT= operand of the line group DCB macro 
instruction is assigned to a line before incoming or outgoing 
transmission begins on that line; once transmission has started, 
no more buffers are available to handle the data involved in the 
transmission. 



1 . A symbol may consist of no more than eight characters, the 
first character being a letter (A through Z, $, #, or @), and 
the other characters being either letters or digits. 

2. No blanks or special characters are allowed in a symbol. 

system interval : a user-specified time interval during which 
polling and addressing are suspended on multipoint lines to 
polled stations. The system interval is specified by the 
INTVAL= operand of the INTRO macro, and may be changed 
during TCAM initialization by a SYSINTVL operator 
command. The INTERVAL operator command tells TCAM to 
begin the system interval. The system interval minimizes 
unproductive polling, minimizes CPU meter time, and 
synchronizes polling on the polled lines in the system. See also 
invitation delay. 

TCU : see transmission control unit. 

telecommunications : any transmission or reception of 
signals, writing, sounds, or intelligence of any nature, by wire, 
radio, or other electromagnetic media. 

teleprocessing : the processing by a computer of data entered 
at a remote station. 

terminal : a point in a system at which data can enter, leave, 
or enter and leave. A terminal can also be a control unit to 
which one or more input/output devices can be attached. See 
component . 

terminal entry : a block of information about each station or 
application. The eight types are cascade, component, 
distribution, group, line, logtype, process, and single. Also 
referred to as terminal-table entry. 

terminal table : an ordered collection of information 
consisting of a control field for the table and blocks of 
information on each line, station, component, or application 
program from which a message can originate or to which a 
message can be sent. 

terminal-table entry : see terminal entry . 



station : either a remote terminal or a remote computer used 
as a terminal. 

status analysis : the function provided by a user-written 
routine in efficiently controlling output to a concentrator on the 
basis of the previous output to that concentrator. The 
user-written routine determines whether output is to continue, 
or is to be delayed. 

subblock : that portion of a BSC message terminated by an 
ITB line-control character. 

switched line : a communication line on which the 
connection between the computer and a remote station is 
established by dialing. Also known as a dial line. 



tete-a-tete : a mode of message handling in which a station 
operating in lock mode is polled by the computer. The station 
responds with a message that ends with a character permitting 
selection to continue. The computer sends a response message, 
from an application program, that the station interprets as a 
positive response. 

text : that part of the message of concern to the party 
ultimately receiving the message (that is, the message exclusive 
of the header, or control, information). 

text buffer : a buffer containing message text only. Compare 
with header buffer. 

text segment : a portion of a message that contains no part 
of the message header. 



symbol : in assembler language, a character or character 
string that represents addresses or arbitrary values. A symbol 
must meet the following requirements: 



transmission : the transfer of coded data by an 
electromagnetic medium between two points in a 
telecommunications network. See also physical transmission. 
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transmission control unit (TCU) : a control unit that serves 
as an interface between communication lines and a computer 
for logical operations. The transmission control units 
supported by TCAM are the 2701 Data Adapter Unit Model 1, 
the 2702 Transmission Control Model 1, and the 2703 
Transmission Control Model 1 . 

transmission priority : refers to the order in which sending 
and receiving occur, relative to each other, for a particular 
station. Transmission priority is specified on a line-group basis 
by the CPRI= operand of the line group DCB macro. The three 
transmission priorities possible in TCAM are send priority, 
equal priority, and receive priority. The exact meaning of each 
priority depends upon the line configuration and type of 
station. See also message priority . 

transparent mode : a mode of binary synchronous 
transmission in which all data, including normally restricted 
data-link control characters, is transmitted only as specific bit 
patterns. Control characters that are intended to be effective 
are preceded by a DLE character. 

TWX : abbreviation of Teletypewriter Exchange Service, a 
semi-automatic switching service provided by AT&T for 
interconnecting public teletypewriter subscribers. 

unit : see buffer unit or work unit. 

warm restart : a restart of the TCAM message control 
program following either a quick or a flush closedown; the 
TCAM checkpoint/restart facility restores the MCP 
environment as nearly as possible to its condition before 
failure. See continuation restart and cold restart. 



WATS : abbreviation for AT&T's Wide Area Telephone 
Service, which provides a special line on which the subscriber 
may make unlimited calls to certain zones on a 
direct-distance-dialing basis for a flat monthly charge. 

worit area : an area of storage related to an application 
program that receives messages or records transferred to the 
application program from the message control program by 
GET or READ macros, and from which messages or records 
are transferred to the MCP by PUT or WRITE macros. The 
size of the work area must be specified in the BLKSIZE= 
operand of the input or output DCB macro associated with the 
data set whose contents are being transferred to or from the 
work area. A work area may be defined either statically (by a 
DC or DS assembler instruction) or dynamically (by specifying 
locate mode in the MACRF= operand of the input DCB 
macro). 

worit unit : the amount of data transferred from the message 
control program to an application program by a single GET or 
READ macro, or transferred from an application program to 
the MCP by a single PUT or WRITE macro. The work unit 
may be a message or a record (or, for QTAM-compatible 
application programs, a segment). 

zero-length buffer : a buffer that has z zero in the PRFSIZE 
field of the buffer prefix, this type of buffer is sent by the Line 
End Appendage to the Message Handler to indicate that there is 
an error on the line. 
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due to uncorrectable I/O error 108 
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closedown 96 
exit 

specifying address for problem program 81 
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specifying user exit 108 
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user routine options 109 
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accounting on a log data set 107 
ACT operand 429 
activating and deactivating the MCP 1 1 1 

sample code 135 
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identifying (TSO) 607 
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ACTVATED operator command 459 

TSO 645 
ACTVBOTH operator command 460 
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address operand 435 
address vector table HI, 629 
dump 518 

generating extension of (TSO) 636 
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for a component 37 
specifying 29 
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TERMINAL macro 31 
TPROCESS macro 47 
alternate destination 
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restriction 95 

sending messages to 290 

specifying 31 

for a component 37 
in the terminal table 47 
ALTMH= operand 639 
application program 353 
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buffers 374-377 

design considerations 374-377 
definition checklist 374-375 
CKREQ macro 444-449 

example 448 
CLOSE macro 380 
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data set definition 358-373 
data transfer 

BSAM/TCAM completion codes 400 
CHECK macro 402 
coding TCAM macros 395-41 1 
GET macro 396 
multiple PUT macros 398 
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PUT macro 398 
READ macro 400 

multiple 400 
WRITE macro 403 
delimiting record for 48 
entering operator commands from 458 
error exits 412-414 

examining a queue control block from 424 
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input data control block 356 
input data set 356 
input DCB macro 361-366 
format of position field 365 



inquiry /rapid response 435 
interface with MCP 356-358 

activating 377-382 

defining components 358-377 

specifying 45 
limiting number of messages sent to 273 
locking to station 241 
MCPCLOSE macro 381 
message flow to 355-356 
message handler for 1 89 
message queues for 

recording status of 505 

specifying where maintained 46 
message retrieval 432 

POINT macro 433 
moving invitation-list contents to work area 420 
moving terminal-table contents to work area 417 
network control 415 

ICHNG macro 428 

ICOPY macro 420 

macro summary 415 

MRELEASE macro 43 1 

operator commands (see network control macro 
descriptions) 

QCOPY macro 424 

TCHNG macro 301 

TCOPY macro 417 
OPEN macro 378 
OS checkpoint restriction 446 
output DCB macro 367 
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password for specific macros 122 
PCB macro 372 
POINT macro 433 
priority 243 
process entry 358 

replacing contents of a terminal table entry 426 
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represented in the terminal table 19 
specified as a secondary operator control station 48 
specifying address of MH for 372 
specifying data/time messages received 47 
specifying maximum destination queues used 

simultaneously 95 
swappable (TSO) 648 
S YN AD AF macro 414 

format of TC AM/SAM message buffer 414 
SYNADexit 412 
TCAM/SAM compatibility 445 
testing in non-teleprocessing environment 353 
work area 356, 383 

defining 383 

specifying size 363, 368 

static definition of 383 
work unit 356, 369 

specifying 387 
areaname operand 
GET macro 396 
ICHNG macro 429 
ICOPY macro 423 
PUT macro 283 
QCOPY macro 425 
READ macro 402 
TCHNG macro 427 
TCOPY macro 417 
WRITE macro 404 
assembler language conventions 3 
assembling the MCP 3 1 8 
AT operand 258 
AT&T TWX Terminals 

device-dependent considerations 596 
line codes for 582 
AT&T 83B3 Terminal 

device-dependent considerations 598 
line code for 581 
AT&T 33/35 Dial Station device-dependent 
considerations 596 
ATTACH macro considerations 539 
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attached subtasks 

listed 543 
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checkpoint 499 
COM WRITE 124 
on-line test 530 
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operator control 453 
ATTEN macro 639 

attention-input error indication (TSO) 649 
attention interrupt 36 

specifying for TSO 633 
attention processing routine (TSO) 639 
attention request error indication (TSO) 649 
audio terminals 

specifying invitation message 12 

use of LOCK macro 241 

use of TERMINAL macro 3 5 
Auto Answer 59 
Auto Call 59 

automatic line numbering (TSO) 649 
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switching to 462 

verifying use on a line 485 
AUTOSTOP operator command 461 
AUTOSTRT operator command 462 
available-unit queue 65 

channel program block work area assigned to 90 

channel program block work area replacement 90 



background (TSO) 628 

base registers for an MH 198 

BFDELAY= operand 3 1 

bidding 9 

binary synchronous transmission ( see also BSC) 6 

transparent mode 8 
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BLANK= operand 

INITIATE macro 239 

LOCK macro 242 

MSGEDIT macro 261 
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PATH macro 283 

PRIORITY macro 287 

SCREEN macro 295 

SETEOF macro 300 

SETSCAN macro 306 

UNLOCK macro 315 
BLKSIZE= operand 106 

input DCB macro 363 

log DCB macro 107 

output DCB macro 368 
block 138 
blocking 661 

outgoing messages for a concentrator 671 
block size 32 

component 38 

overriding for a component 38 

overriding with the MSGFORM macro 32 

specifying for messages in transparent mode to 
a component 38 

specifying for outgoing messages in transparent 
mode 32 
BLOCK= operand 267 
blocked work units 

input data set 364 

output data set 370 
blocking factors 

component 38 

overriding for outgoing messages 266 

specifying 7-8 

specifying for outgoing messages 266 
nontransparent mode 32-33 
BREG= operand 198 
broadcast requests 116 

COMMBUF macro 217 

COMMBUF= operand 1 1 6 
common data areas 1 1 6 
moving data into 2 1 8 



message routing 217 
size of data area 1 1 6 
specifying number of concurrent 1 16 
BSAM DCB macro operands for a log data set 107 
BSAM/TCAM completion codes 404 
BSC 

device-dependent considerations 598 

sending and receiving 598-601 
input format error indicated on message error 
record 549 
buffered station 55 
BUFFER= operand 6 1 8 
buffers 

allocation 73-74 
application program 374 
definition checklist 374 
design considerations 375-377 
control area 64 
deallocating empty units on 202 
defining 

application program 374 
MCP 63-75 
design considerations 70-75 

determining number for read-ahead queue 375 
general 75 
number of units 72 
size 72 
dynamic deallocation (effect on FOB checking) 194 
header 63 

identical characters indicated on message error 
record 548 
checking for 221 
identifying incoming subgroup to handle 201 
initial and maximum number per line 74 
MCP definition checklist 69-70 
message error record indication of insufficient 

number 548 
message header 

using scan pointer 1 49- 1 52 
message 

format of TC AM/SAM S YN AD AF 4 1 4 
outgoing message 

identifying subgroup to handle 205 
overriding size specified on the line group DCB 

macro 3 1 
overriding size specified for a component 38 
prefix 64 

TSO 635, 641 
processing across buffer boundaries 149 
reserving bytes for inserting date/time/sequence 

number 84 
sample format 64 
size 

for line group 63 

overriding 63 

specifying for handling messages for an application 

program 372 
specifying for line 69 
specifying for MCP when messages are for 

application program 363 
specifying for messages destined for logging 

mediurri 51 
specifying for messages to MCP from application 

program 370 
specifying for outgoing messages 31,38 
specifying bytes for date/time/sequence number 373 
specifying initial number for GET/READ operations 373 
specifying initial number for PUT/WRITE 

operations 373 
specifying initial number for receiving 81 
specifying maximum number for lines 82 
specifying program-controlled interruptions for 

allocation/deallocation of 83 
structure 63-65 
text 63 
trace 523 

for logical messages 155 
translation of data in 213 
unit 63 

allocation 66, 67 

as a work area in a channel program block 90 

deallocation 202 
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specifying maximum used simultaneously for main- 
storage queuing 1 1 8 
TSO 630 
specifying number for segments 1 1 8 
specifying size 117 
unit pool 63,65-67 

main-storage message queues data set in 96 
BUFIN= operand 

line group DCB macro 81 
PCB macro 373 
BUFL= operand 

input DCB macro 363 
output DCB macro 370 
BUFMAX= operand 82 
BUFOUT= operand 

line group DCB macro 82 
PCB macro 373 
BUFSIZE= operand 

line group DCB macro 82 
LOGTYPE macro 51 
PCB macro 373 
TERMINAL macro 31 
burst mode restrictions 539 
bus out 

specifying intensive-mode error recording for 497 
check indicated in message error record 549 



calling 35 

between the computer and a switched station 59-61 

busy lines 60-61 

retrying to contact a switched station 35 

specifying time for computer-initiated calls 30 
canceling messages 210 
C ANCELMG macro 2 1 

restrictions 210 

specifying conditional execution 210 

specifying logical connection between mask and message 
error record 210 

TSO 642 
CARRIAGE macro 640 
cascade list 

defining in the terminal table 43 

entry 19 

specifying actual entry in the terminal table 43-44 
CE mode 539 
central computer 5 

channel control check indicated on message error 
record 549 

channel data check indicated on message error record 549 
channel error indicated on message error record 549 
channel program' blocks 89 

determining appropriate number 90 

formula for determining initial number of 91 

free pool 90 

specifying number of 116 
TSO 630 
channel program codes in operator awareness 
message 357 

channel status word indication of I/O error 491 
characters 

checking incoming buffers for identical 221 

data link control 8 

inserting and removing for messages 244 

logical messages 

deleting on input 268 
reblocking on output 267 

parity error indicated on message error record 549 
character sets 555 
CHARS= operand 638 
CHECK macro 

specifying name of data event control block 406 
checklists 

application program buffer definition 374-375 

checkpoint/restart 500-502 

MCP buffer definition 69 

specifying message queues data sets 92 
checkpoint 

coding requirements for obtaining 509-5 12 

coordinating TCAM and OS 446-45 1 
example 339-351 
using DCB exit for 449 



environment records 

example using 507-508 
specifying maximum time between 120 
exit restriction 446-447 
how it works 502-509 
incident record 

example using 339-351 
specifying 212 
incident records 

operator commands causing 490 
making resident 551 
module names and sizes 552 
OS restriction 446-447 
specifying as additional feature 125 
types of records 502-505 
checkpoint data set 104 
DD statement 106 
example of opening 129 

example of updating environment records 507-508 
equation for determining size 510-511 
specifying 103, 104 

as input/output 128 
specifying number of checkpoint request records for 122 
checkpoint DCB macro 105 
checkpoint request record 505 

automatic incident record when data set full 503 
priority used in dividing space for 5 1 1 
specifying data set for 105 
specifying number for checkpoint data set 122 
checkpoint/restart 499-5 1 4 
checklist 499-502 
TSO 648 
CHECKPT macro 212 

specifying incident checkpoint records 212 
CIB= operand 116 
CINTVL= operand 30 
CKPTSYN= operand 47 
CKREQ macro 

checkpoint/restart operands 499-502 

initiating checkpoint request records 509-5 12 

sample use of 507-508 

specifying maximum number of destination queues used 

simultaneously for application programs 122 
using for checkpoint coordination 446-449 
CKREQS= operand 122 
CLOCK= operand 30 
CLOSE macro 

application program 380 

specifying data control blocks 380 
MCP 132 

specifying data control blocks 134 
closedown 

automatic environment checkpoint record during 503 

concentrated-message network 678 

flush 

abnormal termination by wrapping nonreusable 

disk 96 
cold restart following 512 
specifying percentage of nonreusable disk records 

to be used prior to 85 
warm restart following 5 1 3 
initiating through operator control 489 
concentrated-message network 678 
quick 

cold restart following 512 
response to inquiring station in lock mode 436 
warm restart following 513 
restarting from 499 
specifying type 381 
with TSO still active 648 
code 

charts 555-584 

control characters 557 
conventions used in 555 
format of 555 
general notes 557 
nonequivalent characters 557 
substitutions 557 
EBCDIC 569 

hexadecimal equivalents of 6-bit Transcode 57 1 
invalid destination indicated on message error 
record 548 
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line 

AT&TTWX 582 
AT&T83B3 581 
IBM 1030 572 
IBM 1050 573 
IBM 1053 printer 575 
IBM 1060 574 

IBM 2260 (Remote)/2265 575 
IBM 2740 577 

IBM 2741 (Correspondence) 580 
IBM 2741 (EBCD) 579 

IBM 2741 (hexadecimal equivalents of BCD) 578 
IBM World Trade Telegraph ITA2 583 
IBM World Trade Telegraph ZSC3 584 
WU115A 581 
list of translation tables provided 187 
TCAM macro formats 545 
USASCII 570 
CODE macro 213,216,642 

effects on PRIORITY macro 286 

format 215 

handling incoming concentrated messages 

during multiple MH execution 666 
specifying control characters group used 

by (TSO) 638 
specifying type of translation 215 
use with logical messages 214 
CODE= operand 270 
cold restart 

automatic recording of changes in option fields 504 
building "Good Morning" message 131 
following abnormal flush closedown 96 
good morning routine gaining control following 512 
Preformatting DASD message queues data sets 92 
COMEDIT printing utiHty 526 
examples of invoking 527 
PARM= options 526 
command input block (specifying) 1 16 
command reject 

indicated on message error record 549 
specifying intensive-mode error recording for 496 
COMMBUF macro 217 
COMMBUF= operand 1 1 6 
COMP= operand 36 
completion codes for BSAM/TCAM 404 
com.ponent definition 37 
component entry 18 
computer ID sequence 12-13 
COMWRITE data set 

printing contents of 526 
requirements and format 521 
specifying 124 
COM WRTE= operand 1 24 
concentration 653 
closedown 678 

constructing (blocking) outgoing messages 671 
controlling dequeuing for a concentrator 656 
CTB 660, 672 
CTBFORM macro 672 
defining the network 654 
design considerations for handling input 666 
determining source terminal 663 
flow of incoming messages 661 
flow of outgoing messages 674 
handling incoming messages 660 
identifying and verifying source terminal 663 
initializing for 659 
message format 
incoming 660 
outgoing 672 
message retrieval 678 
mid-batch recovery 677 
multiple MH execution 664 
option fields 677 
QACTION macro 667 
queuing by concentrator 658 
queuing techniques for terminals 658 
sample code (concentrators and non- 
concentrators on a multipoint line) 655 
specifying maximum CTBs sent to a concentrator 658 
specifying terminal table entry 655 
specifying terminal type 660 



status analysis 667 

summary of coding requirements 679 

TGOTO macro 665 
conchars operand 169 

INITIATE macro 239 

LOCK macro 242 

MSGTYPE macro 275 

PATH macro 283 

PRIORITY macro 287 

SCREEN macro 295 

SETEOF macro 299 

UNLOCK macro 315 
configurator for on-line test 531 
CONNECT= operand 3 1 6 

C ANCELMG macro 2 1 1 

ERRORMSG macro 226 

HOLD macro 236 

MSGGEN macro 270 

REDIRECT macro 291 
connection error indicated on message error record 549 
conserving main storage 625 
constructing (blocking) logical messages 153 
CONT= operand 196 
contention 9, 17 
contention line 5 
continuation restart 

replaced by cold restart due to faulty checkpoint 
records 513 
control characters 6-7 

in multiple buffer headers 174 

listed 558 

removing 139 

sending 139 

using to vary path of message in MH 173 
control characters group (specifying for TSO) 638 
control information 

buffers 64 

channel program blocks 89 
CONTROL= operand 1 17 
control unit errors indicated on message error 
record 549 

control units supported 539 
CONV= operand 198 
conversational mode 435 

conversion of QTAM application programs 585 
counter-overflow record 496 

access to 498 
COUNTER macro 219 

specifying location of count field 220 

TSO 642 
CPB= operand 116 

TSO 630 
CPINT VL= operand 1 20 
CPRCDS= operand 121 
CPRIOPCL operator command 463 
CPRI= operand 81 

TSO 636 
CPU 

interrupting on output (TSO) 634 
CPU1D= operand 20 
cross-reference table 518 

specifying number of entries in 123 
CROSSRF= operand 123 
CTB 660, 663 

delimiting by character count on output 657 

format on output to a concentrator 672 

inserting delimiter at end of 674 

inserting device id at beginning of 674 

output to a concentrator 675 

specifying bytes to control dequeuing to a 
concentrator 656 

specifying maximum number sent in a transmission 
to a concentrator 658 
CTBFORM macro 672 

return codes 673 
CTBMAX= operand 658 
cutoff indicated on message error record 548 
CUTOFF macro 221 

example 221 

restriction 221 

specifying maximum characters for messages 221 
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TSO 642 

using the ERRORMSG macro with 



221 



DASD 

checkpoint data set record types 502 
message queues data set 

designing for high message traffic 95 
dump 528 
Preformatting 543 
reusable data sets 93 

sample JCL for obtaining printed output of 527 
specifying as input/output 128 
specifying PARM= parameters for printed 
output 528 
specifying for message queues data set 116 
data check 

indicated on message error record 550 
specifying intensive-mode error recording for 496 
data collection by logging messages 5 1 4 
data control block 
checkpoint 105 
dump 518 
input 361 
line group 77 
message queues 103 
output 367 
specifying address 
GET macro 396 
PUT macro 398 
READ macro 401 
WRITE macro 403 
specifying exit address for problem program 81 
specifying for line group 27 
specifying name for data set being closed 134 
specifying name for log data set 5 1 
specifying name for opening application program data 

set 379 
specifying on POINT macro 435 
data event control block (specifying name) 
CHECK macro 406 
READ macro 401 
WRITE macro 403 
data file (delimiting) 299 
data link control 
data operand 257 
data set 

application program 
defining 358 
specifying name of data control block for 

closing 380 
specifying name of data control block for 
opening 379 
checkpoint 105 

DD statement for 106 
example of opening 129 
example of updating environment 

records 507 
equation for determining size 510-511 
specifying 102, 104 
specifying as input/output 128 
specifying number of checkpoint request records 

for 122 
types of records 502 
closing 134 
COMWRITE 

printing contents of 526 
specifying for output 124 
DASD message queues 
Preformatting 92 
specifying as input/output 128 
defining for message concentration 659 
disk (example of writing debugging 

information to) 523-526 
disk message queues 

example of assigning relative record numbers 90 
impending failure indicated on message error 

record 548 
impending fullness indicated on message error 

record 548 
input 

DCB macro 361 



specifying 128 

specifying format and characteristics of work 
unit 363 
input and output DD statements 370 
line group 77 

creating 77 

examples of opening 129 

guideline for specifying as input/output 128 

identifying organization 80 

restriction for coding as output 127 

specifying activation of line 129 

specifying DD statements 86 
log 107,517 

example of opening 129 

list of operands for specifying for BSAM 108 

specifying as output 128 

specifying name of data control block 5 1 

specifying where messages to be queued 52 
logging messages sequentially 5 1 4 
main-storage message queues 

destination queue in 96 

providing warning when nearly full 119 

specifying maximum units used 
simultaneously 119 
main-storage-only queues (lost message 

indication) 548 
MCP 

defining 77 

initialization and activation 127 
message queues 88 

DCB macro 102 

DD statement 104 

destination queues on disk 89 

disk efficiency 92 

dump 528 

examples of opening 129 

main storage 96 

Preformatting disk 543 

sample JCL for obtaining printed output 527-528 

scanning queues in 505 

specifying 102, 106 

specifying one or more 99 

specifying PARM= parameters for printed 
output 528 

specifying when user informed that data set no 
longer crowded 119 

specifying whether on a DASD 1 1 6 

warning when nearly full (TSO) 630 
output 

COMWRITE requirements and format 521 

DCB macro 367 

specifying 128 

specifying format and characteristics of work 
unit 370 
reusable disk queues 93 

automatic environment checkpoint at zone 
changeover 503 

designing for high message traffic 95 

reorganizing 93 
reusable or nonreusable disk destination queue (message 

retrieval) 432 
specifying type 127 
SYS 1 .LOGREC error records 498 
data 

converting to logical messages (incoming) 1 54 

inserting in concentrated output following device id 634 

moving between input and output work areas 384 

processing across buffer boundaries 149 

specifying CPBs for (TSO) 630 

specifying whether to truncate following EOM 302 

transferring between MCP and application 

program 382 
translation of 213 

transmission failure indicated on message error 
record 548 
DATA= operand 227 
data transfer 

BSAM/TCAM completion codes 404 

CHECK macro 406 

coding TCAM macros in an application 

program 395 
GET macro 396 
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issuing multiple READ macros 400 
PUT macro 398 
READ macro 400 
WRITE macro 403 
data-link control characters 8 
date 

format for inserting in header 223 
reserving bytes in buffer for inserting 84 
specifying for messages obtained by application 

program 410 
specifying for process entry 47 
specifying whether to be inserted in header 224 
DATE= operand 47 
DATETIME macro 223 
example 224 

reserving bytes for date/time 373 
restrictions 224 

specifying whether date to be inserted 224 
specifying whether time to be inserted 224 
DATOPFLD operator command 464 
DCB exit 

checkpoint restriction 446 
using for coordination 449 
DCB macros 

application program, closing 366 

BSAM operands for specifying a log data set 107 

checkpoint 105 

BLKSIZE= operand 106 

list of pertinent checkpoint/restart operands 500-502 

specifying data set 105 

specifying ddname 106 

specifying problem program exit list 106 

specifying use of GET and PUT macros for 
access 106 
input 

designating control of message transfer 362 

format of position field 365 

identifying data set organization 80 

list of pertinent checkpoint/restart operands 
operands 500-502 

operands optionally provided by alternate 
source 362 

specifying ddname 363 

specifying EODAD address 365 

specifying format and characteristics of work 
units for input data set 363 

specifying optional fields of work unit 364 

specifying problem-program exit list 365 

specifying size of MCP buffers sent to application 
program 363 

specifying size of record plus optional fields 364 

specifying size of work area 363 

specifying SYNDAD address 365 

specifying type of access to destination 
queue 362 

STOP= operand 366 

summary of work-unit formats 364 
line group 77 

format 79 

identifying data set organization 80 

operands 79 

specifying buffer size 82 

reserving buffer space for date/time/sequence 
numbers 84 

specifying ddname 81 

specifying initial buffers for receiving 81 

specifying initial buffers for sending 82 

specifying invitation delay 80 

specifying maximum buffers for lines 82 

specifying name of MH 83 

specifying name of special characters table 86 

specifying names of invitation lists 82 

specifying problem-program exit list 81 

specifying program-controlled interruption 83 

specifying translation table 85 

specifying transmission priority for line 81 

specifying use of GET and PUT macros for 
access 80 

TSO 635 
message queues 102 

specifying data set 102 

specifying ddname 103 



specifying either reusable or nonreusable disk 103 
specifying percentage of nonreusable disk records 

to be used before flush closedown 104 
specifying problem program exit list 103 
specifying use of GET and PUT macros for 
access 103 
output 

designating control of message transfer 368 
format of position field 369 
identifying data set organization 368 
list of pertinent checkpoint/restart operands 

operands 500-502 
operands optionally provided by alternate 

source 371 
specifying ddname 368 
specifying format and characteristics of work 

upits for output data set 370 
specifying method of transferring messages to 

destination queue 368 
specifying optional fields for work unit 369 
specifying problem program exit list 370 
specifying size of buffers for messages to 

MCP 370 
specifying size of work area 368 
specifying size of work unit plus optional 

fields 369 
specifying SYNAD address 369 
summary of work-unit formats 389-390 
dcbname operand 
CLOSE macro 

application program 380 
MCP 134 
GET macro 396 
LOG macro 246 

TSO 643 
LOGTYPE macro 51 
OPEN macro 

application program 379 
MCP 128 
POINT macro 433 
PUT macro 398 
QRESET macro 443 
READ macro 400 
WRITE macro 403 
DCB= operand 

MCOUNT macro 409 
TERMINAL macro 27 
DD statement 

checkpoint data set 106 
message queues data set 104 
specifying for input and output data sets 370 
specifying for line group data set 86-88 
specifying name of for data control block 8 1 
input DCB macro 363 
line group DCB macro 81 
output DCB macro 368 
DDNAME= operand 

checkpoint DCB macro 106 
input DCB macro 363 
line group DCB macro 81 
log DCB macro 108 
message queues DCB macro 104 
output DCB macro 368 
DEACT operand 429 
deactivating the MCP 131-133 
CLOSE macro 134 
sample activation and deactivation 134 
TC AM with application programs 132 
TC AM with no application program 1 32 
types of closedown 1 3 1 
dead-letter queue specification 1 19 
deallocation 202 

deblocking logical messages (example) 660 
DEBUG operator command 465 
debugging aids 517-530 
activating 465 

basic coding requirements 531 
buffer trace 523 
COMEDIT printing utility 526 
cross-reference table 5 1 8 

specifying number of entries in 123 
dispatcher subtask trace table 521 
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dumps 517 

error messages 517 

example of writing to disk data set 523-526 

line I/O interrupt trace table 519 

specifying number of entries in table 123 
specifying point in routine to gain control when table 
full 123 
message logging 514 

non-teleprocessing TCAM applications 353 
specifying COMWRITE output data set 1 24 
STCB trace table 521 

specifying number of entries in 124 
tracing flow of messages 515 
writing on data set for later printing 520 
decbname operand 

CHECK macro 406 
READ macro 401 
WRITE macro 403 
deconcentration 653 
dedicated line 5 
dedicated system (TSO) 629 
dedicated terminals (TSO) 628 
delay 

changing duration for polling 481 
specifying for invitation 80 
delimiter 

deleting from records for application program 393 
destination field in header for multiple routing 228 
inserting for record 263 

in application program 48 
invitation list 422 
MH macros 191-207 

functions in MH 149 
variable and undefined records 389 
destination 

expediting transmission of messages to 235 

logging 514 

maintaining count of outgoing messages for a 

station 219 
message (specifying on FORWARD macros) 230 
specifying additional 290 
specifying for error message 225 
specifying station to receive intercepted messages 43 1 
specifying type of access to queue 362 
specifying user-written routine to gain control when 
invalid 231 
destination code error indicated on message error 
record 548 

destination field in optional fields in work area 387 
destination queues 

generating for message concentration 655 
in main-storage message queues data set 96 
destinations (canceling messages to multiple) 210 
DEST= operand 226, 230, 291 
ERRORMSG macro 226 
FORWARD macro 230 
REDIRECT macro 29 1 
device-characteristics fields in terminal table 417 
device-dependent considerations 589 
BSC devices 598 
general 598 
IBM 2770 603 
IBM 2780 604 
IBM 2790 604 
IBM 3270 604 
IBM 3670 612 
IBM 3780 613 

sending and receiving 598-601 
TSO/TCAM 3270 649 
start/stop devices 589-598 
AT&T83B3 598 
AT&TTWX 596 
IBM 1030 589 
IBM 1050 589 
IBM 1060 590 
IBM 2260 (Local) 590 
IBM 2260 (Remote) 590 
IBM 2265 592 
IBM 2740 592 
IBM 2740 basic 593 
IBM 2740 basic dial 593 
IBM 2740 model 2 593 



IBM 2740 on switched line 593 

IBM 2740 with station control or station control with 

checking 592 
IBM 2740 with transmit control or transmit control 

with checking 593 
IBM 2741 594 
IBM 2760 594 
IBM 7770 595 

IBM World Trade Telegraph 596 
TPEDIT macro for the IBM 50 Magnetic Data 
Inscriber 613 
device 

malfunction indicated on message error record 550 
not on control unit indicated on message error 

record 549 
not-ready state indicated on message error record 549 
test mode indicated on message error record 549 
device support listed 540 
device types 
BSCl 28 
BSC2 28 
BSC3 28 

TERM= operand 28 
TERMINAL macro 25 
dialing (see calling ) 
dial line as additional feature 125 

TSO 631 
dial-out option as additional feature 125 
DIALNO= operand 29 
DIS ABLE= operand 3 1 6 

disconnection error indicated on message error record 549 
disk data set for debugging information 523-526 
disk queuing 88-96 

advantage of combining checkpoint coordination 

methods 450 
nonreusable 96 

specifying as additional feature 126 
disk 

error handling 491 

I/O-error records 495 

marking message serviced 506 

message retrieval from destination queues 432 

nonreusable 96 

specifying for message queues data set 103 
specifying percentage of records to be used before 
flush closedown 104 
Preformatting message queues data set 543 
reusable 

automatic environment checkpoint of message queues 

at zone changeover 503 
specifying for message queues data set 103 
writing I/O error records to 495 
writing permanent error record on 495 
DISK= operand 116 

dispatcher records of subtask activation 521 
dispatcher subtask trace table 521 
activating 465 

examples of obtaining printed output from 527 
specifying number of entries in 124 
display station (TSO) 

specifying rows and characters per row 63 1 
distribution list 

defining in the terminal table 43 
entry 1 8 

specifying actual entry in the terminal table 43 
DLE 8 

DLQ= operand 119 
DPRIOPCL operator command 467 
DSECOPCL operator command 467 
DSORG= operand 

checkpoint DCB macro 106 
input DCB macro 362 
line group DCB macro 80 
log DCB macro 108 
message queues DCB macro 103 
output DCB macro 368 
DTRACE= operand 124 
DTSAREA= operand 41 1 
dummy entries 

terminal name table 533 
TOTE 530 
OLTERM= operand 20 
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dummy invitation list 83 

dump of message queues data set 528 

sample JCL for printed output 527-528 

specifying PARM= parameters for printed 
output 528-529 
DVCID= operand 

CTBFORM macro 674 

TERMINAL macro 655 
dynamic translation (TSO) 637 



EAU function 606 
EAU operand 606 
EBCDIC code 569 

translation to line code 213 
EDIT= operand 614 
ENDCHAR= operand 

CTBFORM macro 674 

MSGFORM macro 268 

SETEOM macro 301 
end-of-day record 496 

access to 496 
end-of-file 

signaling an application program 394 

specifying EODAD address on input DCB macro 365 
end-of-message 

forced for logical message 155 

I/O errors tested for 601 

signal for an application program 394 
ENTERING operator command 468 
entering 5 
entries 

displaying active (in invitation list) 459 

displaying inactive (for a line) 473 

specifying total number in invitation list 420 
entry 

deactivating for a station 476 

invitation list example 12 

specifying length in invitation list 420 

terminal 38 

activating nonswitched station for entering 468 

terminal-table 

count of Start I/O commands 495 
count of temporary errors 495 

types defined 18 
environment checkpoint records 

specifying size 106 

BLKSIZE= operand 106 
environment checkpoints (specifying maximum time 
between) 120 
environment records 503 

example 507 

how updated 504 

specifying number kept in checkpoint data set 121 
ENVIRON^ operand 629 
EOA character 7 

example using 138 

removing from incoming messages 195 
EOA= operand 231 
EOB checking 

effects of dynamic buffer deallocation on 1 94 

effects of INITIATE macro on 194 

when performed 193 
EOB completion handling 196 
EOB line control character 7, 382, 391 

logical message 154 

removing from incoming message 195 
EODAD address specification on input DCB macro 365 
EODAD= operand 365 
EOF 

signaling an application program 394 

specifying EODAD address on input DCB macro 365 
EOF message indication 299 
EOM 558, 662 

logical messages 154-155 

removing from logical messages 303 

signaling an application program 394 
EOM=ETB operand 303 
EOT line control character 7, 382 

logical messages 1 54 
EOT=t: operand 12 
equipment check 



indicated on message error record 549 
specifying intensive-mode error recording for 497 
ERRECORD operator command 469 

guidelines for using 496 
ERROPT= operand 6 1 5 
error 

counter overflow record written on disk 496 
end-of-day record written on disk 496 
I/O record types 496 
indicated on message error record 547 

TSO 642, 648 
intensive mode recording 496 

displaying current status of 487 
irrecoverable 491 

terminating connection with station due to 491 
logical 

requirements for EOB-checking when user- 
specified 193 
testing for 197 
mid-batch recovery 493 

specifying 35 
permanent I/O record written on disk 495 
recoverable 

operator awareness message indicating 

failures 497 
retrying the block for 493 
specifying EOB checking 193 
retransmitting block containing 236 
specifying mid-batch recovery 21 1 
suspending transmission to station due to 1 89 
temporary 

counter in terminal-table entry for 495 
intensive-mode recording for 469 
I/O record written on disk for 495 
transmission 

requirements for EOB checking 193 
types for which intensive mode may be specified 497 
undefined 

indicated on message error record 549 
error bits described for message error record 547 
error exits for application programs 4 1 2-4 1 6 
error handling 147 
error message 

altering text of 227 
generating an unqueued 269 
sending when errors occur 225 
specifying actual text of 227 
ERRORMSG macro 225 
format 226 
restrictions 225 

specifying conditional execution 226 
specifying destination for error message 226 
specifying error message 227 
specifying user-written routine to complete error message 

processing 227 
versus MSGEN macro 225 
error record 

gaining access to 498 
I/O 495-498 

specifying temporary I/O 469 
error-recovery procedures 

I/O 491 
ETB line control character 7, 8, 382, 391 

removing from incoming messages 195 
ETX line control character 7, 8, 382, 391 

removing from incoming messages 195 
EXEC statement for passing information to user code 182 
execute form on the OPEN macro 129 
executing an MCP (sample JCL) 3 1 8 
exit 

DCB 

checkpoint restriction 445 
using for checkpoint coordination 449 
SYNAD 412 

user-written routine for invalid destinations 23 1 
exit list for problem program 

specifying address on checkpoint DCB macro 106 
specifying address on input DCB macro 365 
specifying address on line group DCB macro 81 
specifying address on message queues DCB 

macro 103 
specifying address on output DCB macro 370 
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EXIT= operand 

ERRORMSG macro 227 

FORWARD macro 231 

QACTION macro 669 
EXLST= operand 

checkpoint DCB macro 106 

input DCB macro 365 

line group DCB macro 81 

message queues DCB macro 103 

output DCB macro 370 
extended lock 437 

removing station from 3 1 4 
EXTEND operand 241 
extracting (deblocking) logical messages 
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failure of system 

cold restart following 512 

example of scanning message queues during 
restart 507 

restarting from 499 

scanning message queues during restart 505 

specifying type of restart for 121 

suggestions for establishing checkpoint 
coordination 447-448 
features 

specifying additional 125 

specifying to conserve main storage 625 
FEATURE^ operand 

INTRO macro 125 

concentrated messages 660 
TSO 631 

TERMINAL macro 36 
TSO 634 
fieldname operand 270 
field addressability requirements 176 
file updating sample program 339-351 
fixed-format work unit 388 
fixed-length work units 

input data set 364 

output data set 370 

specifying size 364 
flush closedown 

ABEND due to wrapping nonreusable disk 96 

automatic environment checkpoint record during 503 

cold restart following 5 1 2 

concentrated-message network 678 

initiating through operator control 489 

specifying in application program 381 

specifying percentage of nonreusable disk records to 
be used prior to 104 

TSO 647 

warm restart following 5 1 3 
FLUSH operand 381 
foreground (TSO) 628 
FORM= operand 664 

format error indicated for BSC input on message error 
record 549 
formatting TCAM macros 545 

conventions used 545 
FORWARD macro 229 

DEST= operand 

format 230 

restrictions 229 

specifying destination for messages 230 

specifying end of destination fields 23 1 

specifying exit routine to gain control for invalid 
destinations 23 1 
free pool queue for channel program blocks 90 
function modification 149 
function operand 256 
functional macros 111, 209 

conditional execution 173 



general poll 

2260 590 

3270 608 
GENERATE macro modified for TCAM 541 
GENPOLOFF operator command 47 1 
GENPOLON operator command 472 
GET macro 396 



specifying address of data control block 396 

specifying address of work area 396 

specifying to gain access to checkpoint data set 106 

specifying to gain access to line group data set 80 

specifying to gain access to message queues data 
set 103 
GMMSG= operand 131 
"Good Morning" message for initial start 1 3 1 
good morning routine gaining control 512 
GOTRACE operator command 472 
group 140-143 

incoming 

required delimiter macro 199, 200, 203 
translating to EBCDIC 2 1 3 

message flow within 166 

outgoing required delimiter macro 207 

queuing concentrated messages by 658 
group entry 1 8 

DSECTof 417 
group operand 256 
grpname operand 

ICHNG macro 429 

ICOPY macro 422 



HANGUP macro 640 
hardware attention 

indicated on message error record 549 

TSO 640 
hardware error (handling for TSO terminal) 640 
header 137 

controlling path of through an MH 275 

format for inserting date and/or time 223 

format of field for input sequence number 297 

logical message 158 

message 138-140 

multiple routing delimiter considerations 23 1 

multiple-buffer 

considerations for user code in an MH 176 
handling 169 

origin field validity 280 

outgoing segment records 245 

scan pointer used for 1 49- 151 
header buffer 63 
header field 

locating 179 
header-only message 137 
header-processing 

functions 139 
HOLD macro 234 

concentrated messages 

design considerations 670 

intercepting output to a concentrator 676 

restrictions 234-235 

specifying conditional execution 235 

specifying duration of hold 236 

specifying type of hold 236 

specifying when retrying to dial a switched station 35 
hold/release 189 



I/O device generation 541 
I/O error 

counter overflow record written on disk 

end-of-day record written on disk 496 

permanent record written on disk 496 

recording 495-498 

record types 496 

recovery procedures 491 

specifying records of 469 

temporary 493 

record written on disk 496 
I/O interrupt trace facility 519 

activating 472 

deactivating 477 
IBM 50 Magnetic Data Inscriber (MDI) 613 

TPEDIT macro for 614 
IBM 1030 Data Collection System 

device-dependent considerations 589 

line code for 572 
IBM 1050 Data Communication System 

device-dependent considerations 589 



496 
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line code for 573 
TSO 

specifying 632 
time-out suppression 635 
translation for group of 1050s 638 
IBM 1053 Printer line code 575 
IBM 1060 Data Communication System 
device-dependent considerations 590 
line code for 574 
IBM 2260/2265 Display Complex 

specifying (TSO) 632 
IBM 2260 (Remote)/2265 Display Complex line 
code 575 

IBM 2260 Display Station device-dependent considerations 
Local 590 
Remote 590 
IBM 2260 Display Station line-address characters 294 
IBM 2265 Display Station device-dependent 
considerations 592 
IBM 23 1 1 Disk Storage Drive 88, 104 
IBM 23 14 Direct Access Storage Facility 88, 104 
IBM 2740 Communication Terminal 

device-dependent considerations 592 
basic 593 
basic dial 593 
station control or station control with 

checking 592 
switched line 593 

transmit control or transmit control with 
checking 593 
line code for 577 
IBM 2740 Model 2 Communication Terminal 
device-dependent considerations 593 
specifying intensive-mode error recording for unusual 

leading graphic response 497 
transmission priority 57 
IBM 2741 Communication Terminal 

device-dependent considerations 594 
line code 578 

BCD hexadecimal equivalents 578 
correspondence 580 
EBCD 579 
specifying as additional feature 125 
TSO 

specifying 63 1 

translation for group of 2741s 638 
IBM 2760 Optical Image Unit device-dependent 
considerations 594 
IBM 2770 Data Communications System 
device-dependent considerations 603 
transmission priority 57 
IBM 2780 Data Transmission Terminal device-dependent 
considerations 604 
IBM 2790 Data Communication SYSTEM 604 

LMD= operand 35, 198 
IBM 3270 Information Display System 604 
coding considerations 61 1 
defining invitation lists 608 
defining terminal tables 608 
dynamic buffering 612 
error handhng 611 
input data stream 605 
outp ut d ata stream 605 
SCREEN macro 606 
general, poll 608 
IBM 3670 Brokerage Communication System 612 
IBM 3735 Programmable Buffered Terminal device-dependent 
considerations 595 

IBM 3780 Data Communication Terminal 613 
IBM 7770 Audio Response Unit device-dependent 
considerations 595 

DATETIME macro 223 
error handling 147 
line lock description 435 
LOCK macro 241 
UNLOCK macro 314 
IBM World Trade Telegraph (WTTA) Terminals 
device-dependent considerations 596 
line code 
ITA2 583 
ZSC3 584 
ICHNG macro 428 



restriction 445 

specifying line group for modifying invitation list 429 

specifying modification or type of modification 429 

specifying password 122, 430 

specifying relative line number for modifying an invitation 
list 429 
ICOPY 420 

restriction 445 

specifying line group containing invitation list to be 
displayed 422 

specifying relative line number to display invitation 
list 423 

specifying work area into which an invitation list is to be 
moved 423 
ID sequence of computer 12 
identification sequence exchange 9, 1 7 

invalid sequence 

indicated on message error record 549 
idle characters 

inserting in message 252 

example 263 
idle line 129 
IDLE operand 129 
lEBUPDTE 

using to make modules resident 55 1 
example 551 
lEDQXA 543 
lEDQXC 528 

sample JCL for invoking 528 

specifying 528 
IFCEREPO system utility program for gaining access to error 
records 498 

inactive entries displayed for a line 498 
INACTVTD operator command 473 
INBLOCK macro 199 
inblock subgroup 140 

processing data across buffer boundaries 149 
INBUF macro 201 

specifying conditional execution 201 
inbuffer subgroup 141 

functions of 141 

identifying beginning of 201 

identifying to handle incoming buffers 201 

translating to EBCDIC 2 1 3 
incident checkpoint records 

automatic environment record when full 504 

example using 507-508 

operator commands causing 490 

specifying 212 

use 490 
incoming data ( 5e^ also incoming message) 

converting to logical messages 154 
incoming group 140 

required delimiter macro 199, 200, 203 

subgroups of 1 40- 1 4 1 

translating to EBCDIC 2 1 3 
incoming message 

blocking 1 53 

checking buffers for identical characters 221 

checking input sequence number 297 

concentrated 660 

multiple MH execution for 664 
design considerations 666 

counting messages for origin station 219 

counting segments for origin station 219 

deblocking 154 

editing 252 

identifying end of MH processing 203 

identifying subgroup to handle buffers 201 

loss indicated on message error record 548 

maintaining record of traffic 245 

removing line control characters from 266 
EOA 195 

sample format 138 

translating 186 
INEND macro 203 
INHDR macro 200 

specifying conditional execution of 200 
inheader subgroups 140 

functions of 141 

identifying beginning of 200 

specifying execution of 200 



{ 



704 OS/MFT and OS/MVT TCAM Programmer s Guide 



translating to EBCDIC 2 1 3 
INHIBIT channel command (TSO) 635 
initializing and activating the MCP 1 1 1 

obtaining disk efficiency 91-92 
INITIATE macro 238 

effects on EOB checking 194 

example 240 

restrictions 238 

specifying conditional execution 239 

specifying use of EBCDIC blank characters 239 
inmessage subgroups 140 

functions of 141 

identifying beginning of 202 

required delimiter macro 202 
INMSG macro 202 
INOUT operand 128 
input data control block 358 
input data set 358 

specifying 128 

specifying DD statement 371 

specifying format and characteristics of work unit 363 
input DCB macro 361-366 
input/output block 

sense byte in operator awareness message 497 

status bytes in operator awareness message 497 
INPUT operand 128 
input queue 

determining number of messages for application 
program 409 
input sequence number 

checking 297 

displaying for last message from a station 487 

format of header field 297 
inquiry/response 435 

coding considerations 438-439 

sample program 328-338 
inquiry/response application use of origin field in work 
area 385 

insert operation 252 
integer operand 

CUTOFF macro 221 

MSGLIMIT macro 274 

ORIGIN macro 281 

PRIORITY macro 287 

SETSCAN macro 305 
intensive-mode error recording 496 

displaying current status of 487 

specifying type 470 
intercepted stations 

destination queue restriction (reusable disk) 95 

displaying list of 474 

indicated on message error record 549 

restriction's on holding messages 1 89 

specifying 234 

specifying another destination to receive messages queued 
for 432 

use of HOLD macro 1 89 
intercept function 

considerations for outgoing concentrated messages 670 

output to a concentrator 676 

queuing requirement 98 

releasing messages 583 
interface for MCP/application program 45, 356-358 

defining components 358-359 
internal code (EBCDIC) 569 
interruption 

I/O error recovery procedures 491 

specifying number of entries in I/O trace table for a 
line 123 

specifying point in routine to gain control when I/O trace 
table full 123 
interval 

automatic environment checkpoint record following 503 
example 507 

between computer-initiated calls to a switched 
station 30 

between inquiry and response 436 

specifying as additional feature 126 

system 61 

activating 474 

TSO 646 
changing duration of 490 



specifying length 120 
INTERVAL operator command 474 

TSO 646 
intervention required 

indicated on message error record 549 
specifying intensive-mode error recording for 496 
INTRCEPT operator command 474 
INTRO macro 113-126 

checkpoint/restart operands 500-502 
COMMBUF= operand 1 1 6 
format 1 1 5 
initialization and activation 1 1 1 

message-concentrating device 659 
list of functions 113 
providing warning when main-storage queues nearly 

full 119 
saving registers when user code handles multiple-buffer 

headers 120 
specifying additional features 125 
specifying COM WRITE output data set 1 24 
specifying duration of mark character 125 
specifying identifier for operator commands 117 
specifying length of system interval 120 
specifying maximum command input blocks used 

simultaneously 116 
specifying maximum destination queues used 

simultaneously for application programs using CKREQ 

macros 122 
specifying maximum simultaneous on-line tests 124 
specifying maximum time between environment 

checkpoints 120 
specifying maximum units simultaneously used for main- 
storage queuing 118 
specifying message lEAOOl to be displayed 125 
specifying name of dead-letter queue 1 19 
specifying name of MCP 115 
specifying number of channel program blocks 1 16 
specifying number of checkpoint request records 122 
specifying number of entries for line trace 123 
specifying number of entries in cross-reference 

table 123 
specifying number of entries in STCB trace 

table 124 
specifying number of environment records kept in 

checkpoint data set 121 
specifying number of units for segments 1 1 8 
specifying password for application program macros 122 
specifying point in routine to gain control when line trace 

table full 123 
specifying primary operator control station 117 
specifying size of buffer unit 1 1 8 
specifying type of lines 125 
specifying type of restart 121 
specifying when user informed that message queues no 

longer crowded 1 1 9 
specifying whether message queues data sets are on a 

DASD 116 
testing return code 126 
TSO 629 
INTVAL= operand 120 
INTVL= operand 

HOLD macro 236 
line group DCB macro 80 
RETRY macro 292 
invalid destination causing user-written routine to gain 
control 232 
invitation 9 

errors indicated on message error record 549 
lines to multipoint BSC stations 12 
specifying delay 80 
invitation characters 1 1 
invitation list 

activating terminal entry of nonswitched station for 

entering messages 468 
constructing 11-17 
deactivating an entry in 476 
delimiter 422 

displaying active entries in 459 
displaying inactive entries in 473 
displaying status of polling for a line 485 
dummy 83 
entry (example) 12 
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identifying active entries in (TSO) 645 
modifying 428-430 

specifying change or type of change for 429 
recording status of 503 
sample format 420-422 
specifying entries for a line 1 1 

example 12 
specifying names of 82 

use of relative line number in specifying entries 82 
invitation message for audio terminals 12 
IN VLIST macro 11-17 
examples 12-17 

contention lines to terminals not assigned ID 
sequences 17 
MASTER= operand 1 3 
nonswitched lines to stations using polling 

characters 14 
output-only lines to stations having no ID 

sequences 17 
switched lines to stations using ID sequences 1 5 
switched lines to terminals using polling 
characters 1 5 
INVLIST= operand 82 

Inward WATS (specifying telephone number) 29 
irrecoverable error 491 

terminating connection with station 493 
ITB control character 8 

retaining in incoming messages 195 
specifying for outgoing messages 267 



KEYLEN= operand 117 



LI 050= operand (TSO) 638 
L2741 = operand (TSO) 638 
LAST= operand 20 
LC= operand 195 
leased line 5 
length operand 

READ macro 402 

WRITE macro 404 
LENGTH= operand 302 
LEVEL= operand 

CANCELMG macro 211 

HOLD macro 236 

TERMINAL macro 30 

TPROCESS macro 48 
LIMIT= operand 425 
line address characters for IBM 2260 294 
line address in operator awareness message 497 
line code 

AT&T83B3 581 

AT&TTWX 582 

IBM 1030 572 

IBM 1050 573 

IBM 1053 printer 575 

IBM 1060 574 

IBM 2740 577 

IBM 2741 (Correspondence) 580 

IBM 2771 (EBCD) 579 

IBM 277 1 (hexadecimal equivalents of BCD) 578 

IBM World Trade Telegraph ITA2 583 

IBM World Trade Telegraph ZSC3 584 
line 

address insertion (sample user code) 296 

arrangement when using WATS 60 

coding the TERMINAL macro 38 

configuration (TSO) 628 
defining 628 

contention 5 

dummy invitation list (output only) 83 

error indicated on message error record 549 

idle 129 

non-contention 5 

nonswitched 5 

stopping transmission for a station 478 

point-to-point 5 

recording changes in status 504 

recording status of 503 

specifying activation for line group data set 129 

specifying intensive-mode error recording for 496 



specifying transmission priority 81 

TSO 635 
specifying types for TCAM 125 
starting or resuming transmission on 484 
stopping transmission 486 
TSO 647 
line control 5-8, 353 
line control block dump 5 1 8 
line-control characters 6 

in concentrated messages 666 

considerations for handling incoming concentrated 

messages 666 
inserting on output 673 
in an application program 7 
insertion 7 

removing by count 266 
when to remove 8 
line entry 

defining in the terminal table 37 
DSECTof 417 
line group 

changing polling delay of 48 1 
characteristics of 77 
data set 77 
creating 77 

examples of opening 129 
guideline for specifying as input/output 129 
restriction for coding as output 127 
specifying activation of lines in 129 
specifying DD statements 86 
DCB macro 79 

TSO 635 
priority 55 

specifying in order to modify invitation list 429 
specifying to display invitation list for a line 422 
starting or resuming transmission on 484 
stopping transmission on 486 
TSO 

specifying MH for 635 

specifying tables for dynamic translation 636 
specifying translation table for 636 
stopping transmission on 647 
translation for IBM 2741s and 1050s 637 
LINEGRP macro (TSO) 628 
line I/O interrupt trace table 519 
activating 465, 472 
deactivating 477 

examples of obtaining printed output 527 
specifying number of entries 123 
specifying point in routine to gain control when table 
full 123 
line lock description 435 

line tone (specifying duration of mark character) 125 
line trace 519 
LINETYP= operand 125 
linkage-editing an MCP (sample JCL) 3 1 8 
list form specified on OPEN macro 129 
LIST= operand 

TLIST macro 43 
TRANLIST macro (TSO) 637 
LISTTA macro (TSO) 628 
LMD= operand 

STARTMH macro 198 
TERMINAL macro 35 
LNSTATUS operator command 475 
LNUNITS= operand 118 
LOCK macro 241 

forms for coding 437 

inquiry/ response coding considerations 438 
logical message use 241 
restrictions 241 

specifying conditional execution 241 
specifying type of lock mode 241 
specifying use of EBCDIC blank characters 242 
lock mode 241,436 
extended 241 

removing station from 314 
message 241 
response to inquiring station during quick 

closedown 436 
specifying type 241 
LOCOPT macro 244 



706 OS/MFT and OS/MVT TCAM Programmer's Guide 



specifying name of option field to be accessed 244 

specifying register to contain address of option 
field 244 

TSO 642 
log data set 

BSAM operands 107 

data control block for 517 

example of opening 129 

specifying as output 128 

specifying name of data control block 5 1 

specifying where messages to be queued 52 
LOG macro 245 

logging messages or segments 517 

restrictions 245 

specifying location of log medium 246 

TSO 643 
logging 

messages 245, 514-518 

segments 245 

types listed 245 
logging on (TSO) 640 
logical errors 

indicated on message error record 549 
TSO 642 

testing for 197 
logical message 138 

blocking to form 153-154 

coding considerations 1 6 1 - 1 64 

constructing 153 
examples 153 

controlling amount of data in 301 

converting incoming data to 1 54 

deblocking to form 1 54 

delimiting on input 301, 199 

forcing EOM 155 

format 153-155 

handling 152 

header 158 

message flow 155 

mid-batch recovery 163, 494 

removing EOM 1 63 , 1 64, 303 

specifying length 164, 302 

specifying MH for 198 

specifying for a station 35 
LOGIC AL= operand 197 
LOGOFF operator command 641 , 644 
logon errors indicated in messages error 
record (TSO) 649 
LOGON macro (TSO) 640 
LOGON operator command 644 
logtype entry 19 
LOGTYPE macro 

logging complete messages 517 

specifying buffer size for messages destined for logging 
medium 5 1 

specifying name of data control block 5 1 

specifying where messages for logging medium to be 
queued 52 
lost data 

indicated on message error record 550 

specifying intensive-mode error recording for 496 
LRECL= operand 

input DCB macro 363 

output DCB macro 368 
LTORG instruction 191 



machine and device requirements 539 
machine end-of-address (EOA) character 139 
MACRF= operand 

checkpoint DCB macro 106 

input DCB macro 362 

line group DCB macro 80 

log DCB macro 107 

message queues DCB macro 102 

output DCB macro 368 
macro instructions (see directory at front of book) 
main-storage message queues data set 

destination queue in 97 

providing warning when nearly full 119 

specifying backup 

nonreusable disk 29 



reusable disk 29 
specifying maximum units used simultaneously 1 19 
TSO 631 
main-storage-only queues 

indicating excessive messages queued 229 
lost message indication 548 
specifying 29 
main-storage queuing 
with disk backup 97 
without disk backup 97 
maintaining orderly message flow 52 
mark character (specifying duration) 125 
mask operand 147 

CANCELMG macro 210 
ERRORMSG macro 225 
HOLD macro 234 
MSGGEN macro 269 
REDIRECT macro 290 
M ASTER= operand 1 3 
MAX= operand 443 
MAXLEN= operand 20 
MB= operand 35 
MCOUNT macro 409 
MCP 

ABEND formatted dump 5 1 8 

activating and deactivating the application program 

interface 377-382 
assembling 318 
buffer definition checklist 69 
buffer size 7 1 

specifying for messages to MCP from application 
program 370 
buffer unit pool 65 
closedown 134 

specifying type of restart following 121 
coding requirements for message logging 5 1 5 
coordinating restart with application program 45 1 
data set initialization and activation 127 
deactivation 131-133 

TC AM with application programs 132 
TC AM with no application program 132 
effect of abnormal termination on application 

programs 450 
execution 318 

automatic environment checkpoint record 503 
starting with catalogued procedures 319 
functional MH macros 209-302 
functions 3 

IBM-supplied (TSO) 628 
initializing and activating 111-131 
interface with application program 356-358 

defining components 358-377 
line control 353 
linkage-editing 318 
priority 353 
putting together 317-351 
reconstructing for restart 499 

specifying number of checkpoint request 
records 1 22 
sample code 320-351 
sections listed 3 17 
specifying name 1 1 5 
specifying size of buffers containing messages for 

application program 363 
starting and restarting 1 1 1 
terminal table 18 

specifying logging complete messages 5 1 7 
tracing flow of messages 5 1 4, 5 1 5 
writing 3 
user tasks in 4 
MCPCLOSE macro 381, 382 
restriction 445 
specifying password 382 
specifying type of closedown 38 1 
considerations for buffered terminals 57 
message 382 
canceled 210 

categorizing for processing 275 
concentration 653 

multiple MH execution 664 
counting number of (TSO) 642 
determining number queued for application program 409 
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displaying number queued (TSO) 646 

dynamically varying path of through an MH 282 

format 137 

incoming ( see incoming message) 

indicating EOF 299 

input sequence number check 297 

length error indicated on message error record 548 

limiting number sent 274 

logging (TSO) 642 

logical 

coding considerations 1 60- 1 64 

dehmiting on input 301 

removing EOM 303 

specifying length 302 

specifying MH for 198 

using CODE macro for 214 
loss avoided during warm restart 5 1 3 
loss due to system failure 505, 506 
marking serviced 505 
multiblock 

specifying mid-batch-recovery for 35,211 
operator awareness 497 
outgoing {see outgoing messages) 
output suspended to a station 234 
parts of 137 

processing as a work unit 390, 391 
record 138 

redirecting when unsent 290 

reentering after system failure to prevent loss 506 
releasing when intercepted 483 
sample formats 138,140 
selective translation 213-214 

example 214 
sequence number 297 

displaying last from a station 487 

displaying last to a station 487 
specifying destination on FORWARD macro 230 
specifying number dequeued for concentrator 656 
testing for operator commands 2 1 3 

example 214 
text 137 
translation 186-187,213 

avoiding 186 
varying path within MH 172 

warm restart after flush closedown to prevent loss 5 1 3 
message and record processing 392 
message block 138 

message buffer format for TCAM/SAM SYNADAF 414 
message concentration 653 
message editing 252 
message error record 547 
bits described 547 
displaying for a line 476 
macros that set bits in 148-149 
setting bits in 491 
TSO 649 

testing at end-of-message 640 
use of TERRSET macro with 3 1 1 
message flow 

example of 2-segment message with multiple-buffer 

header 170 
example of 2-segment message with single-buffer 

header 170 
example of incoming concentrated message 663 
logging 148 

logical messages 155-157 
output to a concentrator 674 
through an MH 165 
to an application program 355 
within MH group 166 
message header 

checking validity of origin field 280 

controlling path of through an MH 275 

delimiting destination field for multiple routing 23 1 

destination codes in 138 

format 137 

date and/or time 223 

input sequence number 297 
locating fields in 179-181 
logical messages 158 
scan pointer used for 149 
using control characters to vary path of message in 



MH 172-173 
message lock 435 
message logging 514-518 

coding requirements 515-517 
complete messages 517 
how it works 5 1 5 
information flow 516 
logging segments 5 1 7 
selectivity 517 
TSO 643 

specifying data control blocks 643 
uses 514 
what to log 5 1 5 
message operand 

LOCK macro 241 
MSGGEN macro 270 
message priority 

after zone reorganization of DASD data set 93-94 
efficient use of 95 
queuing and 52 
message processing 382 
categorizing 275 
guideUnes for specifying 375-377 
Message Processing Program (QTAM) conversion 585 
message queue 

application program 

specifying where maintained 46 
main storage 

providing warning when nearly full 1 19 
specifying maximum units used simultaneously 1 19 
main-storage-only lost message indication 548 
recording status of 503 
scanning 505-509 
TSO 

specifying where maintained 632 
warning when nearly full 630 
message queues data set 88 
DCB macro for 102 
DD statement for 85 
disk 

destination queue in main storage 96 
destination queues on disk 89 
disk efficiency 92 
dump 528 

example of assigning relative record numbers 90 
main storage 96 
Preformatting 543 
opening (example) 129-130 
Preformatting DASD 92 
reusable DASD 93 

automatic environment checkpoint at zone 

changeover 503 
designing for high message traffic 95 
reorganizing 93 
sample JCL for printed output 527 
scanning queues in 505-5()9 
specifying 103, 106 
specifying DASD as input/output 128 
specifying one or more 99 

specifying PARM= parameters for printed output 528 
specifying type in terminal table 27 
specifying when user informed that message queues no 

longer crowded 1 1 9 
specifying where maintained 29 
specifying whether on a DASD 1 1 6 
message retrieval facility 432 

in a concentrated-message network 678 
POINT macro 432 
message routing 146 
control 3 

techniques of coding for one or more destinations 229 
message segments 63,138,166 
expediting transmission of 238 
maintaining incoming count for origin station 219 
translation of 213 
message subblock 138 
message switching sample program 321-327 
message transmission 

between start-stop and BSC stations 7 
dynamically varying path through an MH 282 
establishing contact for 9 
lost data indicated on message error record 548 
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specifying continuation after retry exhausted 196 
specifying termination after retry exhausted 195 
stopping for a nonswitched station 478 
suspending 189 

output 234 
suspension to intercepted station indicated on message 
error record 549 
MF= operand 

application program 379 
MCP 129 
MFT-II 539 
MH 

base register requirements 198 

coding for application program 1 89 

conditional execution of functional macros 173 

controlling path of message through 275 

defining beginning of (TSO) 639 

delimiter macros 191-207 (see directory at front of 

book) 
designing 137 

conditionally executing macros 173-175 

delimiter macros 1 9 1 -207 

functional macros 209-3 1 6 

hold/release facility 189 

list of groups/subgroups/delimiter macros 192 

message flow 165 

message format 137 

message header 138 

message translation 186-188 

order of macro specification 149 

selecting functions 145 

steps in 190 

structure 138 

user code in 176-185 

variable processing in 172 
dynamically varying path of message through 282 
functional macros 209-316 (see directory at front of 

book) 
functions provided 145 

error handling 147 

function modification 149 

message editing 145 

message routing 146 

record keeping 147 

system control 148 

validity checking 146 
gaining access to option fields 21-24 
groups 140 

delimiters 142 

order of 1 42 
incoming group 1 40- 1 4 1 
macro return codes 1 82 
macros 

delimiter 137 

functional 137 

order of specif ication 149 
macros and corresponding subgroups listed 144 
message flow 165 

example of 2-segment message with multiple-buffer 
header 170 

example of 2-segment message with single buffer 
header 168 

message processed by application program 166 

switched message 165 

within group 166 
minimum requirements 142 
multiple execution for incoming concentrated 

messages 664 
organization 140 
outgoing group 143 
purpose of 137 

specifying address of for an application program 372 
specifying for line group 

TSO 635 
specifying for logical messages 198 
specifying type (TSO) 629 
specifying whether dedicated to TSO 639 
subgroups and corresponding macros listed 144 
subgroups 

delimiters 142 

functions of 140-142 

order of 142 



TCAM line groups in mixed environment 644 
TSO line groups in mixed environment 644 
types of macros 137 
user code in 176-185 

formula for determining bytes resulting from 176 

locating header field 179 

locating option fields 179 

macro return codes 1 82 

multiple-buffer header considerations 176 

obtaining information from EXEC job-control 
statement 1 82 

open subroutines 176 

requirements and restrictions 176 

sample activation of closed subroutine 178 
variable processing in 172-173 
varying path of message in 173 
MH macros (see directory at front of book) 
TCAM 191 
TSO 638 
MH return codes 1 82 
MH routine (TSO) 641 
MH= operand 

line group DCB macro 79 

TSO 635 
PCB macro 372 
TGOTO macro 665 
MHGET macro 247 

user specified work area, MH 247 
MHPUT macro 249 

user specified work area, MH 249 
mid-batch-recovery 493 

in a concentrated-message network 677 
for incoming concentrated messages 665-666 
retransmitting erroneous blocks 236 
specifying 35,211 
MINLN= operand 614 
mixed environment 628, 644 

specifying 629 
modules associated with operator commands 552 
MOVE= operand 307 
MRELEASE macro 43 1 

for terminals attached to a concentrator 676 
restriction 445 
specifying password 432 

specifying station to receive intercepted messages 43 1 
MSGEDIT macro 252 

avoiding coding problem 257 
example of coding problem 254 
examples 261-265,293 

deleting and replacing data 264 

deleting data followed by contracting 264 

deleting miscellaneous data 264 

deleting several characters 264 

deleting single character 264 

inserting control symbols in segments 265 

inserting data after every n bytes 263 

inserting data in header buffer 262 

inserting idle characters 263 

inserting line addresses 293 

multiple inserts and removes 265 

replacing data 262 

simultaneously inserting and replacing data 262 
format 256 
limitations 254 
restrictions 254, 259 
scan pointer effects 254, 256 
specifying beginning of data to be removed 258 
specifying data to be inserted 256-258 
specifying data to be removed 256-258 
specifying end of character string to be removed 259 
specifying insert or remove operation 256 
specifying location at which data to be inserted 258 
specifying type of function 256 
speed of execution 253 
structure of operand groups 256 
MSGFORM macro 266 

deleting characters on input 268 

reblocking on output 267 

SENDTRP= operand 267 

specifying outgoing blocking factors 267 

specifying outgoing ITB characters 267 

specifying subblock delimiters for output 267 
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specifying whether transparent mode used 267 
MSGGEN macro 269 

restrictions 271 

specifying conditional execution 270 

specifying data for 270 

specifying logical connection between mask and message 
error record 270 

specifying type of translation 27 1 

TSO 642 

versus ERRORMSG macro 225 
MSGLIMIT macro 273 

restrictions 273 

specifying number of messages for a transmission 
sequence 273 

when ineffective 
MSGTYPE macro 275 

examples 277 

EXIT= operand 276 

specifying path of message through an MH 275 

specifying use of EBCDIC blank characters 276 

TABLE= operand 276 
MSMAX= operand 119 

TSO 630 
MSMIN= operand 119 

TSO 630 
MSUNITS= operand 118 

specifying value in 118 

TSO 631 
multiblock messages 

mid-batch recovery 493 
specifying 35,211 
multiple-buffer header 167 

considerations for user code in an MH 176 

handling 167 
multiple destinations 229 

canceling messages to 210 

DEST= operand 230 

validity checking 232 
multiple disk arms 75 

multiple PUT macros, application program 398 
multiple READ macros 400 
multiple retrieval 433 
multiple-subgroup restrictions 171 
multiple WRITE macros, application program 398 
multiple-wait capability 406, 41 1 

example 412 
multiplexer channel 539 
multiprocessing 539 
multipoint 5 
MVT 539 



network control facilities 415-432 
network control macros 415 

ICHNG macro 428 

ICOPY macro 420 

MRELEASE macro 43 1 

QCOPY macro 424 

TCHNG macro 426 

TCOPY macro 417 
network reconfiguration 498 

application program macro instructions for 498 

operator commands for 498 
NOENTRNG operator command 476 
non-contention line 5 
NONE operand 215 
nonreusable disk queues 96 

specifying 29 

message retrieval from destination queue 432 

Preformatting 543 

specifying for message queues data set 102 

specifying percentage of records to be used before flush 
closedown 104 
nonswitched line 5 

activating station on 460 

activating station's terminal entry for entering on 468 

preventing station transmission to CPU 476, 478 
nontransparent mode 8 

specifying 267 
NOTRACE operator command 477 
NOTRAFIC operator command 478 



NTBLKSZ= operand 32 
nucleus generation 542 



OBR extension for TCAM 495 
OLT ( see on-line test) 
OLTERM= operand 20 
OLTEST= operand 124 
on-line test 530 

advantages 531 

devices supported 532 

invalid request indicated on message error record 548 

specifying maximum that may occur simultaneously 124 

system requirements 532 
coding 532 

JCL for TOTE/OLTs 538 
main-storage 532 
TOTE 531 

tests 531 

TOTE facilities 531 
OPDATA= operand 

TERMINAL macro 33 

TPROCESS macro 48 
OPEN macro 371-373 

checkpoint/restart operands to be considered 501 

examples of opening data sets 129 

initialization and activation 1 1 1 

specifying activation of line for line group data set 129 

specifying list and execute forms 129 

specifying name of data control block 379 

specifying name of DCB macro 128 

specifying type of data set 128 
operand formats 545 
operating system generation 541 
operator awareness message 497 

for I/O error 493 

specifying display of lEAOOOl 125 
operator commands 459 (see directory at front 
of book) 459 

entering from application program 458 

examples 456 

incident checkpoints resulting from 490 

incident records caused by 504 

incorrectly formatted 458 

listed by areas affected 492 

listed by type of operation 587 

operation types 454 

queuing responses to 457 

responses 457 

specifying 456 

specifying identifier for 1 1 7 
operator control 453 

activating debugging aids 465 

activating line trace 446 

activating nonswitched station for 
transmission 460 

activating nonswitched station's entry for 
entering 468 

activating the system interval 474 

changing duration of polling delay 481 

changing duration of system interval 490 

checkpointing commands 490 

command format 453 

commands listed by operation 587 

considerations 677 

STOPLINE macro 677 
LMD 677 
EOT 677 
EOM 677 

deactivating line trace 477-478 

displaying active invitation list entries 459 

displaying current status of intensive-mode 
recording 487 

displaying list of inactive entries for a line 473 

displaying list of intercepted stations 474 

displaying message error record for a line 475 

displaying name of primary station 467 

displaying names of secondary stations 467 

displaying polling status of a line 485 

displaying queue control block fields 482 

displaying sequence number of last message to/from a 
station 487 
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displaying station's option fields 480 

displaying station status 487 

displaying station's relative line number 484 

displaying status field for a line 475 

entering commands from application program 459 

establishing primary station 463 

incident records caused by commands 504 

incorrectly formatted commands 458 

initialization for 453 

initiating closedown 489 

inserting data in option fields 464 

intensive-mode error recording 470, 496 

making resident 551 

preventing nonswitched station entering to CPU 476 

preventing transmission for nonswitched station 478 

primary station 

displaying name of 467 
operator awareness message 497 

queuing responses to commands 457 

releasing intercepted messages 483 

replies to a component 37 

responses to commands 457 

sample commands 456 

secondary stations 

displaying names of 467 

specifying an application program in the terminal 
table 48 

specifying commands 456 

specifying primary station 1 17 

specifying secondary stations in the terminal table 36 

specifying temporary I/O error records 469 

starting or resuming line transmission 484 

stopping transmission for line or line group 486 

suspending transmission to a station 488 

switching to Auto Poll 462 

switching to programmed polling 461 

testing for operator commands 214 
example 214 

TSO considerations 645 
opfield operand 

COUNTER macro 220 

CTBFORM macro 673 

LOCOPT macro 244 

MSGLIMIT macro 274 

PATH macro 283 
TSO 643 
OPFLD= operand (TSO) 638 
OPTCD= operand 

checkpoint DCB macro 106 

input DCB macro 364 

message queues DCB macro 103 

output DCB macro 369 
OPTFIELD operator command 480 
option fields 

automatic recording of changes at cold restart 504 

defining in the terminal table 21 

displaying for a station 480 

examining contents 417 

gaining access to 

specifying name for 244 

specifying register to contain address for 244 

TSO 642 

in a concentrated-message network 677 

inserting data in 464 

locating 244 

macros that may gain access to 21 

modifying 426 

moving contents to work area 417 

not found 244 

recorded on environment checkpoint record 504 

recording changes in status 504 

recording status 504 

reserving space in 21 

setting bit in (TSO) 643 

specifying actual data to be inserted 33, 38, 48 
example 38, 49 

specifying address of translation table (TSO) 638 

specifying incident checkpoint record of 212 

specifying type and length in terminal table 22-24 

specifying work area to contain 419 
option table 21 

displaying fields in 480 



specifying address of field in 244 
OPTION macro 21-24 

coding examples 23-24 

specifying type and length of option field 22-24 
optional fields 

defining in work area 384-387 
origin and destination 384 
position field 385 
SAM prefix 386 

format of relative positions in work area 387 

included in specifying length of work unit 
READ macro 402 
WRITE macro 404 

included in specifying size of work area 362 

included in specifying record size in work area 363 

included in specifying work-unit size in work area 368 

specifying for work unit 363, 369 
ORDER= operand 12 

origin code error indicated in message error record 647 
origin field 

in work area 384 

message header validation 280-281 

relative position among optional fields in work area 387 
ORIGIN macro 280 

identifying and verifying source of concentrated 
message 663 
return codes 664 

specifying character count for origin fields in a message 
header 281 

variable functions of 280 
origin station 

determining for a concentrated message 663 

maintaining incoming count 
of messages 219 
of message segments 219 

maintaining count of outgoing message segments 
for 219 

recording for message obtained by application 
program 411 
OS generation 540 

outboard recorder extension for TCAM 495 
OUTBUF macro 205 

specifying conditional execution 205 
outbuffer subgroups 140 

functions of 1 42 

identifying to handle outgoing buffer 205 

translating to line code 2 1 3 
OUTEND macro 207 
outgoing group 140-142 

required delimiter macro 207 

subgroups of 1 4 1 - 1 42 
outgoing message 

counting segments for destination station 21-9 

editing 252 

format of concentrated message 672 

identifying subgroup to handle buffers 205 

inserting sequence number 297 

maintaining count for destination station 219 

maintaining record of traffic 245 

sample format 138,140 

specifying blocking factors 266 

specifying priority handling for 286 

specifying subblock delimiters for 267 

translating 186 
outgoing subgroup translation to line code 213 
OUTHDR macro 204 

specifying conditional execution 204 
outheader subgroup 1 40- 141 

functions of 141 

identifying beginning of 204 

translating to line code 2 1 3 
outmessage subgroup 

functions of 1 42 

required delimiter macro 206 
OUTMSG macro 206 

specifying conditional execution 206 
output data control block 358 
output data set 358 

COMWRITE requirements and format 521 

DCB macro 367-371 

specifying DD statement 368 

specifying format and characteristics of work 
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unit 370 
specifying type on OPEN macro 128 
output DCB macro 367-371 
OUTPUT operand 128 
output sequence number 297 

displaying last for a station 487 

inserting 297 
Outward WATS (interval between computer-initiated calls to 
switched stations) 30 
overrun 550 

indicated on message error record 550 

specifying intensive-mode error recording for 496 



parameter list on OPEN macro 379 
parity character error indicated on message error 
record 549 

password for application program macros 122 
PASSWRD= operand 

ICHNG macro 427 

INTRO macro 122 

MCPCLOSE macro 382 

MRELEASE macro 432 

TCHNG macro 427 
path switches 173 

altering to vary path of message through an MH 282 

specifying byte (TSO) 643 

specifying execution of inheader subgroup 200 
path switching delimiter macros 149 
PATH macro 282-285 

example 284 

specifying conditional execution 283 

specifying path switch setting 282-284 

specifying path-switch byte to be used 283 

specifying use of EBCDIC blank characters 283 

TSO 643 
PATH= operand 

INBLOCK macro 199 

INBUF macro 201 

INHDR macro 200 

INMSG macro 202 

OUTBUF macro 205 

OUTHDR macro 204 

OUTMSG macro 206 
PCB macro 372-374 

specifying bytes for date/time/sequence number 374 

specifying initial buffers to handle data in user work 
area 373 

specifying initial buffers to handle data obtained by 
GET/READ 373 

specifying MH for an application program 372 

specifying size of buffers for an application 
program 372 
PCB= operand 46 
PCI= operand 83 
permanent-error record 495 

access to 498 
physical transmission 153 
point-to-point Une 5 
POINT macro 433 

multiple retrieval 433 

restriction 445 

specifying data control block for message retrieval 435 

specifying required address of a field 435 
POINT= operand 306 
POLLDLAY operator command 481 
polling 9 

changing duration of delay 481 

determining type for a line 421 

displaying status of a line with respect to 485 

general 

2260 590 
3270 608 

specific 

3270 608 
suspension of 

timeout exceeded indicated on message error 
record 550 
polling characters 9 

for polled stations 1 1 
position field 385 

guidelines for using in work area 376 



relative position among optional fields in work area 387 
prefix 64 

primary operator control station 
command for establishing 463 
displaying name of 467 
operator awareness message 497 
specifying 1 1 7 
PRIMAR Y= operand 1 1 7 
printing utility 

COMEDIT 526 

examples of invoking 527 
PARM= options 526 
lEDQXC (PARM= options) 528 
priority 

application program 353 
equal 

nonswitched contention stations 58 
nonswitched polled station with programmed 

polling 55 
nonswitched polled stations with Auto Poll 56 
MCP 353 
message 52-55 

after zone reorganization of DASD data set 80 
busy lines 59 
efficient use of 95 
queuing concentrated message by 658 
receive 

nonswitched polled stations with Auto Poll 56 
nonswitched polled stations with programmed 
polling 56 
send 

nonswitched contention stations 58 
nonswitched polled stations with Auto Poll 56 
nonswitched polled stations with programmed 
polling 56 
specifying 30 

for terminals attached to a concentrator 657 
permissible levels for messages on a process 
queue 48 
transmission 55-59 

displaying (TSO) 646 
efficiency when receive specified 95 
queuing concentrated messages by 658 
specifying for concentrator-attached terminals 657 
specifying for line 81 
priority handling for outgoing messages 287 
PRIORITY macro 287 

effect of CODE macro on 286 
example 288-289 

specifying conditional execution 286 
specifying for a message 286 
specifying priority level for a message 286 
specifying use of EBCDIC blank characters 287 
private library definition 3 1 9 
problem program exit list 

specifying address on checkpoint DCB macro 106 
specifying address on message queues DCB macro 103 
process control block 

defining in the MCP 356-360 
dump of 518 

specifying name of in the terminal table 46 
PCB macro for 372-374 
process entry 19 

application program requirements 357 
specifying date/time messages received 47 
PROCESS^ operand 302 
processor/library generation 542 
PROGID= operand 115 
program-controlled interruption 

buffer allocation considerations 74 
for output to a concentrator 675 
specifying for buffer allocation 83 
program EO A 139 

example 138 
programmed polling 56 

determining use on a line 420 
switching to 461 
protection password for application program macros 122 
purging destination queue at restart 47 
PUT macro 398 

specifying address of data control block 398 
specifying address of work area 399 
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specifying to gain access to checkpoint data set 106 
specifying to gain access to line group data set 80 
specifying to gain access to message queues data 
set 103 



QACTION macro 667 
QBACK= operand 50 
QBY= operand 27 
QCNTRL= operand 656 
QCOPY macro 424 

LIMIT= operand 425 

restriction 445 

specifying name of terminal table entry whose queue 
control block is to be displayed 425 

specifying name of work area for displaying queue control 
block 425 
QRESET macro 443 

dcbname operand 443 

MAX= operand 443 
QSTART macro 447 

in checklist for checkpoint/restart 501 
QSTATUS operator command 482 

TSO 646 
QTAM 

converting application programs 585 

macro facilities listed 5585 
queue 

determining number of incoming messages for application 
program 409 

specifying maximum number of main-storage 
units (TSO) 631 

specifying where maintained for TSO messages 632 
queue control block 

displaying fields in 482 
TSO 646 

dump of 518 

examining 424-425 

generating (TSO) 636 

master 424 

specifying name of terminal table entry for 
displaying 425 

priority 424 
queue reset facility 440 

dcbname operand 443 

MAX= operand 443 

QBACK= operand 50 

QRESET macro 443 

TPROCESS macro 45 
queue status (TSO) 646 
QUEUES^ operand 

LOGTYPE macro 52 

TERMINAL macro 28 
TSO 632 

TPROCESS macro 46 
queuing and message priority 52-55 
queuing 

disk 88-96 

advantages and disavantages 89 

intercept function requirement on 98 

main storage 96 

with disk backup 98 

without disk backup 97 

indicating excessive messages queued 229 

messages for one or more destinations 229 

retrieve function requirement on 98 

specifying one or more methods 98 

specifying main-storage as additional feature 126 

specifying reusable disk as additional feature 126 

techniques listed 88 

terminals attached to a concentrator 658 
queuing by destination 88 
queuing by line 

considerations for 53 

example 54-55 
queuing by terminal 

considerations for 53-54 

example 54-55 
quick closedown 

automatic environment checkpoint record during 503 

cold restart following 5 1 2 

concentrated-message network 678 



initiating through operator control 489 
response to inquiring station in lock mode 
specifying in application program 381 
TSO 647 



436 



warm restart following 
QUICK operand 381 
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read-ahead queue 355, 375 

formula for number of buffers required for 375 
role in message flow 165 
READ macro 400 

issuing more than one per process queue 384 
specifying address of data control block 401 
specifying address of work area 402 
specifying initial buffers to handle data obtained by 373 
specifying length of work unit plus optional fields 402 
specifying name of data event control block 385 
specifying SF 401 
READY macro 130 

initialization and activation 1 1 1 
reblocking outgoing records 266 
RECDEL= operand 48 
RECDLM= operand 410 
receiving 5 

BSC considerations 600 
RECFM= operand 

input DCB macro 363 
log DCB macro 108 
output DCB macro 370 
TPEDIT macro 614 
record 382 

checkpoint request 503 

priority used in dividing space for 5 1 1 
specifying data set for 106 
specifying number for checkpoint data set 1 22 
control 502 
counter overflow 496 
deleting delimiters 41 1 
delimiting for an application program 48 
end-of-day 496 
environment checkpoint 503 
example using 507 
how updated 503 
error 

displaying current status of intensive-mode 
recording 487 
gaining access to 498 
intensive mode recording 496 
I/O error types 496 
incident checkpoint 504 

automatic environment record when full 503 
example using 507 
operator commands causing 490 
specifying 212 
use 504 
inserting delimiter (example) 263 
maintaining for message traffic 245 
variable length reblocking on output 266 
permanent-error 493 
processing as a work unit 392 
specifying size 363 
types in checkpoint data set 502 
record keeping 1 47 
record and message processing 393 
record processing guidelines 376 
recoverable error 

operator awareness message indicating failure 497 
retrying the block 493 
specifying EOB checking 193 
REDIRECT macro 290 

specifying additional destinations 291 
specifying conditional execution 291 
specifying connection between mask and message error 
record 291 
( register ) operand 

CODE macro 215 
LOCOPT macro 244 
registers 

saving when user code handles multiple-buffer 

headers 120 
specifying for an MH 198 



Index 713 



relative line number 

CPU calling a station 59 

displaying for a station 484 

example of TERMINAL macros arranged according 

to 40 
specifying 27 

to display invitation list 422 
to modify an invitation list 429 
station calling the CPU 58 
use in invitation list 82 
releasing intercepted messages 483 

output to a concentrator 676 
RELEASE operand 235 
remove operation 252 
REMOVE= operand 303 
REPLACE= operand 6 1 6 
RESERVE= operand 

line group DCB macro 84-85 
PCB macro 373 
RESMXMIT operator command 483 

resuming transmission to a terminal attached 
to a concentrator 677 
response (see inquiry/response) 

response keywords at INTRO execution time 114-115 
restart 473 

building "Good Morning" and "Restart in Progress" 

messages 130-131 
checkpoint data set for 105-106 
cold 512 

after abnormal flush closedown 96 
building "Good Morning" message 130-131 
good morning routine gaining control 

following 512 
reformatting DASD message queues data sets 92 
conditions required for various types 514 
continuation 513 

replaced by cold restart due to faulty checkpoint 
records 512 
coordinating MCP and application program 450 
maintaining continuity of sequence numbers 298 
purging destination queue 47 
scanning message queues after system 

failure 505 
TSO considerations 648 
types 512 

specifying 121 
warm 512 

replaced by cold restart due to faulty checkpoint 
records 512 
restart in progress routine (use) 506 
restarting the MCP 122 
RESTART= operand 122 
RESULT= operand 307 
retrieval of messages 432 
POINT macro 433 
queuing requirement 98 
retry count exhausted 

continuing message transmission 196 
terminating message transmission 195 
RETRY macro 292 
RETRY= operand 35 
return codes 1 82 

CTBFORM macro 673 
ORIGIN macro 664 
TGOTO macro 665 
retrying the block 493 
reusable disk queuing 93-96 

advantage of combining checkpoint coordination methods 

for 451 
automatic environment checkpoint at zone 

changeover 503 
designing for high message traffic 96 
Preformatting 543 

retrieving messages from destination queue 432 
specifying 29, 126 

for message queues data set 102 
reverse break feature (TSO) 

specifying 634 
reverse interrupt (RVI) 197, 598 
rln operand 

ICHNG macro 429 
ICOPY macro 422 



RLN= operand 27-28 
RLNSTATN operator command 
RSMSG= operand 131 
RVI ( see reverse interrupt) 



484 



SAM prefix 386 

SAM/TCAM compatibility 445 

sample programs 320-3 5 1 

file updating with checkpoint coordination 339-35 1 

inquiry /response 330-338 

message switching 323-327 
scanned message queues 505 
scan pointer 149 

automatically moving 149 

coding considerations 151-152 

error indication on message error record 547 

example of use 1 5 1 

MH macros not dependent upon 169 

moving 304-308 

redirecting concentrated messages to another MH 666 

use of with CODE macro 213 
SCREEN macro 293-296 

2260 

XRE operand 295 
XLA operand 295 
XDC operand 295 

3270 

EAU operand 606 

example 296 

return codes 295 

specifying conditional execution 295 

specifying type of Write operation 294 

specifying use of EBCDIC blank characters 295 

use of MSGEDIT macro with 293 
SCRSIZE= operand (TSO) 63 1 
SCT= operand 86 
SDR extension for TCAM 495 
secondary operator control station 1 16 

displaying names of 467 

specifying an application program as 48 

specifying in the terminal table 36 
secondary storage for message queues data sets 1 16 
SECTERM= operand 

TERMINAL macro 36 

TPROCESS macro 48 
segments 138 

counting (TSO) 642 

expediting message transmission using INITIATE 
macro 238 

incoming 

maintaining count for origin station 2 1 9 
maintaining record of 245 

outgoing 

maintaining count for destination station 219 
maintaining record of 245 
seizing the line 5,17 
selection 9, 18 

errors indicated on message error record 547 
sending 5 

BSC considerations 598 
SENDTRP= operand 267 

sense byte in input/output block of operator awareness 
message 497 
sense count 497 
SEQUENCE macro 297 

reserving bytes for sequence number 373 
sequence number 

displaying for last message to or from a station 487 

errors indicated on message error record 547 

input 

checking 297 

format of header field 297 

internal counter for 297 

maintaining continuity during restart 298 

output 

inserting 297 

recording status of fields containing 505 

reserving bytes in buffer for 373 
service bit 506 
service facilities 453 

checkpoint/restart 499 
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I/O-error recording 495 

I/O error-recovery procedures 491 

message logging 514 

network reconfiguration 498 

operator control 453 
SETEOF macro 299 

specifying conditional execution 299 

specifying use of EBCDIC blank characters 300 
SETEOM macro 301 

EOM=ETB operand 303 

multiple MH execution 666 
SETSCAN macro 304-308 

examples 307-308 

format 305 

specifying direction of scan pointer movement 306 

specifying new location of scan pointer 305 

specifying register to contain address of last 
character 307 

specifying use of EBCIDIC blank characters 306 

specifying whether scan pointer to remain stationary 
after a move 307 
SF operand 

READ macro 401 

WRITE macro 403 
SIMATTN macro (TSO) 641 
simulated attention (TSO) 641 

indicated in message error record 649 
single entry 1 8 
single entry DSECT 417 

SIO command counter in terminal table entry 495 
skipchars operand 305 
SLOWPOLL macro 309 
special characters table name (specifying) 85 
specific poll 

3270 608 
START command 319 

Start I/O command counter in terminal-table entry 495 
start-stop transmission 7 

device-dependent considerations 589 
starting and restarting the MCP 1 1 1 

building "Good Morning" message 130 
STARTLINE operator command 484 
ST ARTMH macro 1 93- 1 98 

format 194 

function of 140-142 

inquiry/response coding considerations 437 

removing line control characters 195 

retaining line control characters 195 

reverse interrupt 197 

specifying continuation of transmission after retry 
exhausted 195 

specifying EOB completion handling 196 

specifying number of base registers 198 

specifying termination of transmission after retry 
exhausted 195 

specifying tete-a-tete interaction 196 

testing for logical errors 197 

TSO 639 
STARTUP= operand 121-122 
STATDISP operator command 485 
station 5 

BSC device contention 13 

defining a component belonging to 18 

defining in a group 1 8 

defining individually 18 

designating to receive user-specified error 
messages 226 

displaying input sequence number of last message 
from 487 

displaying option fields 480 

displaying output sequence number of last message to a 
station 487 

displaying relative line number of 484 

displaying status of 487 

error indicated on message error record 547 

intercepted 

indicated in operator control display list 475 
indicated on message error record 547 
restriction on type of destination queue 95 
restrictions on holding messages 189 
specifying 234 
specifying another station to receive messages 



queued for 43 1 
use of HOLD macro 189 
invalid identification sequence indicated on message error 

record 549 
INVLIST macro 1 1 

limiting number of messages sent to 273 
locking to appHcation program 241 
maintaining count of outgoing messages for 219 
master 13 

MASTER= operand 13 
nonswitched 

activating 459 

activating terminal entry for entering 468 
preventing transmission to CPU 476 
stopping transmission for 478 
operator control 

command for establishing 463 
specifying secondary in the terminal table 36 
origin 

maintaining count of incoming message segments 

for 219 
maintaining count of incoming messages for 219 
maintaining count of outgoing message segments 
for 219 
primary operator control 
displaying name of 467 
operator awareness message sent to 497 
removing from extended lock mode 3 1 4 
secondary operator control 
displaying names of 467 
specifying an application program 47 
slave 13 
specifying incident checkpoint records of option fields 

belonging to 212 
specifying intensive-mode error recording for 496 
specifying logical messages for 35 
suspending transmission to 1 89, 488 
switched 

retrying to dial 35,292 
station control block dump 5 1 8 
station queue, displaying priority level for TSO 646 
statistical data recorder extension for TCAM 495 
statname operand 

MRELE ASE macro 43 1 
TCOPY macro 418 
status analysis 667 

format of logical data using 667 
specifying for outgoing messages 657 
status bytes in operator awareness message 497 
status field displayed for a line 475 
status information for debugging 465 
STCB trace table 521 
activating trace 465 

examples of obtaining printed output 577 
specifying number of entries for table 124 
STOP= operand 195, 366 
STOPLINE operator command 486 

considerations for buffered terminals 57 
TSO 647 
STOPLN macro (QTAM) 586 

considerations for buffered terminals 57 
STSTATUS operator command 487 
STX control character 7, 8 

removing from incoming messages 195 
SUBBLCK= operand 267 
subblock 138 
size 33, 38 
subgroups 1 40 

arrangement 142 

executing by setting switch 173 

functions of 140 

inbuffer 

identifying beginning of 201 
identifying to handle incoming buffers 201 
translating to EBCDIC 213 
inheader 

identifying beginning of 200 
specifying execution of 200 
translating to EBCDIC 214 
inmessage 

identifying beginning of 202 
required delimiter macro 202 
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outbuffer 

identifying to handle outgoing buffer 205 
translating to line code 205 

outgoing 

translating to line code 213 

outheader 

identifying beginning of 204 
translating to line code 213 

outmessage 

required delimiter macro 206 

restrictions on multiple 1 7 1 
subtasks 

keeping record of activation 521 

attached 543 

optional 

attaching checkpoint 499 
attaching COMWRITE 520 
attaching on-line test 531 

required 

attaching operator control 453 
SUSPXMIT operator command 488 

suspending concentrated output 676 
switched line 5 

defining for input or input/output 18 

identifying station for incoming calls 280 

retrying to dial station 35, 398 

use of TERMINAL macro 39 
switches 173 
switch operand 282 

TSO 643 
SYNAD 

exit 412 

input to routine 413 

register contents on entry to 413 

status indicators of routine 414 
SYNAD address 

specifying on input DCB macro 365 

specifying on output DCB macro 369 
SYNAD AF 413,414 

format of TC AM/SAM message buffer 414 
SYNAD = operand 

input DCB macro 365 

output DCB macro 369 
SYNADRLS macro 413 
SYSl.LINKLIB (making transient modules 
resident) 551 

SYSl .LOGREC (gaining access to error records on) 498 
SYSCLOSE operator command 489 

closing a concentrated-message network 678 

considerations for buffered terminals 57 

TSO 647 
SYSGEN 540 

SYSINTVL operator command 61-62, 490 
system control 148 
system failure 

cold restart following 5 1 2 

continuation restart following 5 1 3 

restarting from 499 

scanning message queues during restart 505 
example 507 

specifying type of restart for 122 

suggestions for establishing checkpoint 
coordination 447 
system generation considerations 540 
system interval 61-62 

activating 474 
TSO 646 

changing duration of 490 

specifying length 120 
system macros issued in an MH 175 
system preparation 539 
system records of changes in status 504 



tablename operand 215 
TBLKSZ= operand 33 
TCAM/SAM compatibility 445 

use of SAM prefix 386 
TCAM 

closing system 380 
TSO 647 

determining presence in CPU from non-buffered 



terminal 42 1 
machine and device requirements 539 
macro formats 545 

conventions used 545 
macros (TSO) 
changes to 628 
invalid for TSO MH 643 
non-restricted 641 
operand-restricted 642 
making transient modules resident 551 
modules associated with operator commands 552 
multiprocessing 389 

running QTAM application programs 585 
service facilities 453 
specifying during system generation 540 
system preparation 539 
TCAM-dedicated system 629 
TCAM/TSO mixed environment 644 
TCAMON operator command 644, 645 
TCHNG macro 426 
restriction 426 
specifying name of work area containing replacement 

for terminal table entry 427 
specifying password 122, 427 

specifying terminal table entry whose contents are to be 
replaced 427 
TCOPY macro 417 
restriction 417 
specifying station whose terminal-table contents are to be 

moved 418 
specifying work area into which terminal table contents are 
to be moved 419 
telecommunications system 

macros used for controlling 148 
specifying line configuration and device 
requirements 540 
telephone number of a station (specifying) 29 
teleprocessing network indentification 
temporary error 496 

counter in terminal-table entry 496 
temporary-error record 496 
access to 498 

intensive-mode recording for 496 
TERM= operand 28 

TSO 632 
terminal characteristics (TSO) 

defining 628 
terminal entry types 18-19 
terminal errors (TSO) 639-640 
TERMINAL macro 25-42 

abnormal termination due to improperly specified message 

queues data set 28 
addressing characters for specifying a component 36 
coding for a component 37-38 
coding for a line 38 

controlling dequeuing for a concentrator 656 
defining a component 37, 38 
defining a line entry 38 

delimiting CTB on output by character count 657 
establishing priority levels for concentrator-attached 

terminals 657 
for concentrators and non-concentrators on a multipoint 

line 655 
message concentration 654 
format 26 
multiple macros arranged by relative line number 

(example) 41 
operands 27-36 

specifying a component 37 
options for specifying terminal type 27 
overriding block size with the MSGFORM macro 32 
queuing by concentrator 658 
queuing by groups for concentrated messages 658 
relevant operands when specified for a line 40 
specifying addressing characters 29 
specifying alternate destination 3 1 

component 36 
specifying block and subblock sizes for a component 

accepting messages in nontransparent mode 38 
specifying block size for outgoing messages 
nontransparent mode 32 
transparent mode 33 



i 
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specifying block size of messages in transparent mode 

to a component 38 
specifying buffer size for outgoing messages 3 1 
specifying data control block name for line group 27 
specifying data for option fields 33 

example 34 
specifying delay between message blocks sent to a 

buffered station 3 1 
specifying interval between computer-initiated calls to a 

switched station 3 1 
specifying maximum number of CTBs sent to a 

concentrator 658 
specifying priorities 30 
specifying relative line number 27 
specifying secondary operator control stations 36 
specifying status analysis 657 
specifying subblock size for outgoing messages in 

nontransparent mode 32 
specifying telephone number of a station 29 
specifying terminal table entry for a concentrator 655 
specifying time for computer-initiated calls 30 
specifying type of message queuing 27 
specifying where message queues to be maintained 27 
specifying whether a component is to accept replies to 

operator commands 38 
summary determining use for a line 39 
TERM= operand 28 
TSO 631 

use of relative line number in dialing 28 
using for audio lines 39 
terminal 

checking for malfunction (TSO) 642 
concentrator-attached 

queuing techniques for 658 
defining 5-61 

determining number that are accepting 420 
determining total number on a line 420 
modifying Write operation 293 
recording changes in status 503 
recording status of 503 
specifying type (available options) 28 

handling concentrated messages 659 

TSO 632 
types supported 539 
terminal table 1 8 
constructing 1 8 
defining boundaries 19 
defining option fields 21 
DSECT format 417 
dump 5 1 8 
macro instructions 

LOGTYPE 51 

OPTION 21 

TERMINAL 25 

TLIST 43 

TPROCESS 45 

TTABLE 19 
reserving space in an option field 21 
specifying data for option fields (example) 49 
specifying last entry in 20 
specifying logging complete messages 517 
specifying secondary operator control stations 36 
types of terminal entry 1 8 
terminal table entry 

count of start I/O commands 495 
count of temporary errors 496 
examining contents 417 
modifying 426 

specifying for a concentrator 655 
specifying for a concentrator-attached terminal 655 
specifying name for displaying queue control block 425 
specifying name of for replacing contents 427 
termination 

application program 450 

due to not specifying user error-analysis routine 108 
overlaying records on message queues data set 96 
specifying user exit 108 

wrapping nonreusable disk during flush closedown 96 
terminology 5 
termname operand 

QCOPY macro 424 
TCHNG macro 426 



temporary I/O error 

intensive-mode recordings 496 

specifying records 469 
TERRSET macro 311 

setting a bit in the message error record 3 1 1 

TSO 642 

using ERRORMSG macro with 3 1 1 
tete-a-tete interaction (specifying) 1 96 
text 137 
text buffer 63 
text-only message 137 

text transfer error indicated on message error record 549 
TGOTO macro 665 

multiple MH execution 666 

return codes 665 
THRESH= operand 

FORWARD macro 232 

message queues DCB macro 104 
threshhold indication in message error record 549 
time 

format for inserting in header 224 

logging 515 

recording for message obtained by application 
program 41 1 

reserving bytes in buffer for 84, 373 

specifying for process entry 47 

specifying whether to be inserted in header 21 
time-of-day for computer-initiated calls 30 
Time Sharing Option ( see TSO) 
TIME= operand 224 
timeout exceeded 

indicated on message error record 550 

specifying intensive-mode error recording for 496 
timer feature (TSO) 631 
time-out suppression (TSO) 635 
TLIST macro 43 

defining either distribution list or cascade list 43 

example of extended list of entries 44 

specifying entry for distribution list or cascade list 43 
TO operand 259 
TOPMSG= operand 125 
TOTE 530 

facilities 532 

invalid request indicated on message error record 548 
TP Op code in operator awareness message 498 
TPDATE macro 410 
TPEDIT macro 614 
TPROCESS macro 

checkpoint/restart operands 502 

delimiting a record for the application program 48 

interface between MCP and application program 45 

operands 46 

purging destination queue at restart 47 

QBACK= operand 50 

specifying actual data for option fields 48 
example 49 

specifying alternate destination 47 

specifying application program as secondary station 48 

specifying name of process control block 46 

specifying permissible priority levels for messages on a 
process queue 48 

specifying where application program message queues 
maintained 46 
TPUT macro (TSO) 634 
TRACE= operand 123 
TRANLIST macro (TSO) 637 
TRANS= operand 85 

TSO 636 
transferring data between MCP and application 
program 382 

transient modules (making resident) 551 
translation 186-188 

avoiding 186 

of data in buffers 213 

selective 215 

specifying type 215 

TSO 642 

dynamic 637 

for groups of IBM 2741s and 1050s 637 
translation tables 187 

formatting 186 

list of TC AM-provided 1 87 
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overriding for a line group 2 1 3 
providing 187 
specifying 7 

for line group 85 

user 215 
TSO 

error indicated in message error record 649 

for group of IBM 2741s and 1050s 637 

specifying address in option field 638 

specifying control characters group for 
dynamic translation 638 

specifying for line group 636 

TCAM-provided 637 
transmission 6 

dynamically varying path of message through an 

MH 282 
limiting number of messages to a destination 273 
logical message 152 
maintaining count of messages or message 

segments 219 
specifying continuation after retry exhausted 196 
starting or resuming on lines 484 
stopping for a nonswitched station 478 
stopping for line or line group 486 

TSO 647 
suspending 1 89 

suspending output to a station 234, 488 
transmission control unit 

examining sense byte for I/O error 491 
transmission priority 55 

efficiency when receive specified 95 
nonswitched contention stations 58 
nonswitched polled stations 55 

Auto Poll 56 

TCAM program poll 56 

using buffering 57 
specifying for line 8 1 

TSO 635 
switched stations 58 

BSC 598 

non-BSC 59 

TWX 597 
transparent mode 8 

specifying for message transmission 267 
TREXIT= operand 123 
TSINPUT macro (TSO) 636 
TSO 627 

background 628 

bits in message error record 648 

buffer prefix 635,641 

buffer unit (specifying maximum for main-storage 

queuing) 631 
channel program block (specifying number) 630 
checkpoint/restart 648 
closedown 647 
commands 

LOGOFF 644, 645 

LOGON 644, 645 

TCAMON 644, 645 
DCB macro (line group) 635 
dedicated system 629 
dedicated terminals 628 
dynamic translation 642 
errors 

indicated in message error record 642, 648 
logical 642 

terminal (handling) 640 

testing I/O at end-of-message 640 
flush closedown 647 
foreground 628 
interval (activating) 646 
line group DCB macro 635 
logging on 640 

logical error indicated in message error record 642 
MCP 

IBM-supplied 628 
message error record 648 

testing at end-of-message 640 
message logging 643 
message queues 630, 63 1 , 632 
messages 

counting 642 



displaying number queued 646 

logging 643 
MH 

defining beginning of 639 

specifying for line group 635 

specifying type 629 

specifying whether dedicated to TSO 639 
mixed environment 628, 644 

specifying 629 

non-dedicated terminals 644 
operator control considerations 645 
optional features (defining) 628 
option field 

gaining access to 642 

setting bit in 643 

specifying address of translation table 638 
quick closedown 647 
receive priority (specifying) 636 
restart considerations 648 
reverse break feature (specifying) 634 
send priority (specifying) 636 
simulated attention 639, 641 
STARTMH macro 

ALTMH= operand 639 
stopping transmission for line or line group 647 
system interval (activating) 646 
TCAM 

3270 device dependent considerations 649 

closing 647 
TCAM macros 

changes to 628 

invalid in TSO MH 644 

non-restricted 641 

operand restricted 642 
TCAM/TSO mixed environment 644 
terminal characteristics (defining) 628 
TERMINAL macro 631 

QBY=T operand 632 

QUEUES=operand 632 
translation 642 

dynamic 637 

for group of IBM 2741s and 1050s 637 
translation table 

error indicated in message error record 649 

for group of IBM 2741s and 1050s 637 

specifying address in option field 638 

specifying control characters group for dynamic 
translation 638 

specifying for line group 636 

TCAM-provided 637 
transmission priority for lines 635 

specifying for lines in a line group 636 
TSO-dedicated system 629 
TSO macros 636 

non-restricted 641 

ST ARTMH-dependent 64 1 
TSO Message Handler macros 638 
TSO-only environment 628 
TSO/TCAM mixed environment 628, 644 
TTABLE macro 20 

OLTERM=operand 20 
specifying length of terminal table name 20 
typelength operand 22 
typename operand 246 
TYPE= operand 

QACTION macro 43 
TLIST macro 40 
TYPETABL macro 313 



undefined error indicated on message error record 549 
undefined-format work unit 388 

input data set 365 

output data set 368 
undefined-length work unit size 368 
unit 

allocation 65-67 
examples 67 

deallocating from end of buffer 202 

determining number needed 72 

specifying maximum simultaneously used for main-storage 
queuing 119 
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specifying number for segments 1 1 8 
specifying size for buffers 117, 118 
warning when main-storage message queues data 
set nearly full (TSO) 630 

unit exception 

indicated on message error record 549 
specifying intensive-mode error recording for 496 

unit pool 63, 65-67 

UNITSZ= operand 118 

UNLOCK macro 314 

CONNECT=: operand 3 1 6 

DIS ABLE= operand 3 1 6 

examples 314 

inmessage subgroup considerations 316 

inquiry Aesponse coding considerations 437 

specifying conditional execution 3 1 5 

specifying use of EBCDIC blank characters 315 

USASCII code 570 

user code in MH 175 

formula for determining bytes resulting from 176 

user error indicated on message error record 549 

UTERM= operand 37 



388 



variable-format work unit 
input data set 364 
output data set 370 
variable processing within MH 
variable record delimiter 389 
VERCHK= operand 615 



172 



wait state, application program 405 

WAIT macro for testing BSAM/TCAM completion codes 405 

warm restart 512 

replaced by cold restart due to faulty checkpoint 
records 512 
WATS (arrangement of TCAM lines) 60 
WDC operation 293 , 295 
WLA function 293 
WLA operand 295 
work area 356, 382 

addressability requirements 176 
contents described in position field 369 
defining 383 

defining optional fields 384 
origin and destination 384 
position field 385 
SAM prefix 386 
dynamic definition of 383 

format of relative positions of optional fields in 387 
guidelines for using position field in 376 
including optional fields when specifying size 

of 364, 369 
message handler 
format 247, 249 
MHGET macro 247 
MHPUT macro 249 
user specified 247, 249 
moving contents of option fields to 417 
moving data between input and output 384 
optional fields included in specifying record size 364 
origin field in 384 



position field in 385 
format 365, 369 
SAM prefix in 386 
specifying address 
GET macro 396 
READ macro 401 
specifying from which terminal table contents are to be 

moved 427 
specifying initial buffers to handle data from 373 
specifying into which invitation list contents are to be 

moved 422 
specifying into which terminal table contents are to be 

moved 419 
specifying on PUT macro 399 
specifying size 368 
specifying station whose terminal table contents are to be 

moved to 418 
static definition of 383 
work unit 356,382 

effect of type and format on determining size of 394 
formats 388 

input DCB macro summary 389 
output DCB macro summary 390 
optional fields included in specifying work-unit size 369 
processing 

for a message 390 
for a record 392 
specifying 387 
specifying input data set format and 

characteristics 363 
specifying length including optional fields 
READ macro 402 
WRITE macro 404 
specifying optional fields for 363, 369 
specifying output data set format and 

characteristics 370 
specifying size 368 
types 390 
WRE function 293 
WRE operand 294 
Write-at-Line-Address 293 
WRITE macro 403 

specifying address of data control block 404 
specifying length of work unit plus optional fields 404 
specifying name on data event control block 397 
Write operation 

modifying for terminals with display screens 293 
specifying type for 2265s (Remote) or 2260s 294 
verifying type in effect 294 
WTOR at INTRO execution time 114-115 
WTTONE= operand 125 
XDC function 295 
XDC operand 295 
XLA function 295 
XLA operand 295 
XRE function 295 
XRE operand 295 
example 507 



6-bit Transcode (hexadecimal equivalents) 571 
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